Skip to content

lab-1-setup.md

Latest commit

 

History

History
233 lines (171 loc) · 17.2 KB

lab-1-setup.md

File metadata and controls

233 lines (171 loc) · 17.2 KB

Лабораторная работа #1: Настройка окружения

Общие инструкции

Цели

  1. Ознакомиться с общей процедурой приема лабораторных работ.
  2. Познакомиться с инфраструктурой GitHub + GitHub Actions и принятым там процессом разработки (на примере Integration Manager Workflow).
  3. Получить первичные навыки использования таких инструментов как Git, GoogleTest и CMake.

Задачи

  1. Подготовить рабочее окружение
    • Установить и настроить все необходимые инструменты
    • Получить исходные коды, построить проект и запустить имеющиеся тесты
    • Включить тестирование своего проекта на GitHub Actions
  2. Реализовать несколько модульных тестов на уже существующий компонент
  3. Интегрировать свои изменения в центральный репозиторий
    • Прислать изменения в виде pull request
    • Добиться прохождения автоматических проверок на GitHub Actions
    • Пройти рецензию кода

Общий порядок выполнения

  1. Install. Инсталлируйте и настройте Git, CMake и IDE для языка С++ (подойдут Visual Studio, QtCreator, CLion).
  2. Fork. Зарегистрируйтесь на GitHub. Создайте свой форк центрального репозитория и склонируйте его к себе на машину.
  3. Build & Test. Соберите проект и убедитесь в его работоспособности, запустив модульные тесты на компонент complex-number. Изучите общую организацию данного компонента.
  4. Code & Test. В отдельной ветке Git выполните задание лабораторной работы:
    • Создайте новую ветку Git с именем вида YOUR-NAME-lab1.
    • В директории devtools-course-practice/modules/complex-number/test/ заведите свой личный файл для тестов с именем вида test_YOUR_NAME_complex_number.cpp.
    • Реализуйте в этом файле не менее 3 тестов на класс ComplexNumber. Если некоторые из ваших тестов будут падать по причине некорректной, на ваш взгляд, реализации, стоит оставить тесты, но приписать в начало их имени ключевое слово DISABLED_. В таком случае преподаватели смогут устранить найденный дефект.
    • Убедитесь, что ваши тесты компилируются и запускаются вместе с остальными.
  5. Code Review. Когда убедитесь в корректности своего кода локально, пошлите свои изменения в виде pull request в центральный репозиторий:
    • Убедитесь, что ваши тесты компилируются и запускаются вместе с остальными на GitHub Actions.
    • Пройдите рецензию кода (два сокурсника и преподаватель) и исправьте все высказанные замечания.

Типичные ошибки

Ниже приведены типичные ошибки, при наличии которых лабораторная не будет принята:

  • Работа велась в ветке с именем main.
  • Изменение файлов вне своего личного файла. Так, например, файл complex-number/test/test_simple.cpp должен остаться неизменным.
  • Ваши тесты должны быть уникальны, нельзя просто копировать уже имеющиеся. Постарайтесь протестировать какие-то интересные и нетривиальные случаи.

Детальные инструкции

Первичная настройка

  1. Зарегистрируйтесь на GitHub. Предпочтительно использование никнейма, из котого понятно ваше имя.

  2. Установите и настройте себе Git, используя инструкции например отсюда или отсюда.

  3. Создайте форк нашего проекта, затем клонируйте репозиторий к себе на рабочую машину. Все необходимые инструкции можно найти здесь.

  4. Зарегистрируйте центральный репозиторий в локальном репозитории Git под именем upstream. Это потребуется, чтобы получать актуальное состояние ветки main оттуда. Для того, чтобы сделать это и проверить успешность, выполните следующие команды:

    $ git remote add upstream https://github.com/UNN-ITMM-Software/devtools-course-practice
$ git remote -v

  5. Инсталлируйте приложение CMake.

  6. Инсталлируйте IDE QtCreator, или любую другую по вашему выбору. В принципе, вы можете разрабатываться в IDE Microsoft Visual Studio, любой другой IDE, или в простом текстовом редакторе. CMake допускает все эти варианты.

Подробные инструкции вы можете найти здесь.

Выполнение лабораторной

  1. Создайте новую ветку, в которой вы будете работать над лабораторной:

    $ cd devtools-course-practice
$ git checkout -b SECONDNAME-FIRSTNAME-lab1

  2. Сгенерируйте проект для какой-либо IDE при помощи CMake. ВНИМАНИЕ: настоятельно рекомендуется использовать так называемый out-of-source build, чтобы отделить исходники проекта от результатов компиляции. Далее скомпилируйте проект, открыв его в IDE, запустите тесты и убедитесь, что все они проходят.

  3. Полезно выполнить тестирование в командной строке. Для этого нужно открыть консоль, перейти в корень директории с проектом и запустить команду ниже. Имено эта команда используется для тестирования на CI сервере, поэтому полезно уметь пользоваться ей локально.

    $ ctest -VV -S devtools_test.cmake

  4. Создайте новый файл для своих собственных тестов. Ему нужно дать имя вида test_YOUR_NAME_complex_number.cpp и разместить в директории devtools-course-practice/modules/complex-number/test/. Можете использовать следующую заготовку для начала.

    // Copyright 2017 Korniakov Kirill

#include <gtest/gtest.h>

#include "include/complex_number.h"

TEST(Korniakov_Kirill_ComplexNumberTest, Can_Create_Zero) {
    // Arrange
    double re = 0.0;
    double im = 0.0;

    // Act
    ComplexNumber z(re, im);

    // Assert
    EXPECT_EQ(re, z.getRe());
    EXPECT_EQ(im, z.getIm());
}

    Требования к файлам:

    • Первая строка должна быть комментарием вида:

      Copyright [year] <Copyright Owner>

    • В качестве отступов не должны использоваться символы табуляции. Нужно использовать последовательность из пробелов.

    • Подробнее про требования по стилю кода можно прочитать здесь - Google C++ Style Guide.

  5. Далее нужно убедиться, что ваш файл добавлен в проект. Он должен подцепиться автоматически, нужно только перегенерировать проект при помощи CMake. IDE либо сама предложит это сделать, либо нужно запустить CMake в корневой директории проекта. В консоли вы должны увидеть результат выполнения теста следующего вида:

    [----------] 1 test from Korniakov_Kirill_ComplexNumberTest
[ RUN      ] Korniakov_Kirill_ComplexNumberTest.Can_Create_Zero
[       OK ] Korniakov_Kirill_ComplexNumberTest.Can_Create_Zero (0 ms)
[----------] 1 test from Korniakov_Kirill_ComplexNumberTest (0 ms total)

  6. Теперь вы готовы к тому, чтобы реализовать свои собственные тесты. Добавьте не менее 5 штук в свой собственный файл, всякий раз убеждаясь, что проект все еще компилируется, и все тесты проходят. Для этого нужно запускать тестирование в IDE или из командной строки:

    $ ctest -VV -S devtools_test.cmake

    Время от времени делайте локальные коммиты:

    $ git add test_YOUR_NAME_complex_number.cpp
$ git commit -m "Added new tests for lab1"

  7. Далее сделайте git push в свой форк проекта:

    $ git push origin HEAD

  8. Если впоследствии нужно будет что-то поправить, используйте следующие команды:

    # Editing file with tests...
$ git add test_YOUR_NAME_complex_number.cpp
$ git commit -m "Updated tests"
$ git push origin HEAD

Когда вы посчитаете, что закончили реализацию тестов, можно перейти к процедуре интеграции в центральный репозиторий.

Тестирование на GitHub Actions

  1. GitHub предлагает пользователям встроенную систему тестирования с большим разнообразием конфигураций. Однако существуют и другие подобные сервисы, например Travis CI.

  2. Сразу после открытия pull-request, CI автоматически запускает инструкции, описанные файлами из папки .github/workflows.

  3. В названии pull-request нужно указать свою фамилию и номер лабораторной, например "Корняков - Лабораторная работа #1".

  4. CI добавляет на страницу с pull request зелёную галочку, если сборка и тестирование прошли успешно или красный крест в случае ошибки.

  5. Если выявились какие-то проблемы, зайдите на страницу с билдом, исправьте ошибки и обновите pull-request:

    # Editing files ...
$ git add test_YOUR_NAME_complex_number.cpp
$ git commit -m "Updated tests"
$ git push origin HEAD

    Повторяйте шаги выше до тех пор, пока тестирование не будет успешно проходить.

Рецензия кода

  1. Первым делом необходимо убедиться, что успешно прошло тестирование на GitHub Actions. Вероятность того, что что-то пойдет не так -- невелика, поэтому скорее всего можно будет сразу перейти к следующему шагу. Однако, возможны две ситуации: ошибка без конфликта слияния (merge conflict), либо конфликт слияния. Первая ситуация исправляется легко, простым добавлением коммитов в свою ветку как было описано выше. Вторая ситуация -- более сложная, поскольку вам предстоит обновить свою ветку относительно текущего состояния ветки main в центральном репозиторий. Для этого выполните следующие команды:

    # Resolving merge conflicts
$ git checkout -b SECONDNAME-FIRSTNAME-lab1
$ git remote update
$ git rebase upstream/main

    Далее в ручном режиме вам предстоит устранить конфликт слияния, и обновить свою ветку:

    # Resolve the conflict manually
$ git ci -a -m "Resolved merge conflict"
$ git push --force origin HEAD

  2. Далее необходимо пройти ревью кода от двух своих сокурсников. Пригласите их к дискуссии, дабавив в pull reqeust комментарий вида @github-name (например @kirill-korniakov).

  3. Если будут замечания к вашему коду, вам нужно добавлять коммиты в свою ветку, и пулл-реквест будет автоматически обновляться.

    # Editing file with tests ...
$ git add test_YOUR_NAME_complex_number.cpp
$ git commit -m "Updated tests"
$ git push origin HEAD

  4. Рецензия считается незавершенной, пока вы не получите два approve (Pull Request -> File chenged -> Review changes -> Approve -> Submit review) от коллег. Его наличие означает одобрение ваших изменений от них. Затем необходимо пригласить одного из интеграционных менеджеров и пройти окончательное ревью.

После прохождения ревью код будет влит в основную ветку main, и лабу можно считать сданной. Датой сдачи лабораторной будет считаться дата вливания.