Workflow quick reference

Регистрация и подготовка аккаунта

• Зарегистрироваться на BINP/GCF кластере, для этого необходимо обратиться к Андрею Сухареву или Дмитрию Максимову

• Зайти на stark.inp.nsk.su (доступно только внутри института) или proxima.inp.nsk.su (доступно из любого места)

Эти машины близки по конфигурации и имеют общий /home

Для взаимодействия с git-сервером используется протокол ssh с авторизацией по ключам.

• Если ранее не был создан, то создать ssh ключ командой

ssh-keygen

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

В результате в поддиректории ~/.ssh/ будут созданы два файла id_rsa и id_rsa.pub Полные пути к создаваемым файлам будут отображены на экране.

• Зайти на сервер gitlab https://git.inp.nsk.su/ (логин и пароль теже, что и для входа на stark/proxima)
• Зарегистрировать публичную часть этого ключа в своём аккаунте, т.е. поместить содержимое файла ~/.ssh/id_rsa.pub в форму по ссылке ниже

https://git.inp.nsk.su/profile/keys

Создние рабочего репозитория (форк)

Открыть центральный репозиторий

https://git.inp.nsk.su/sctau/aurora

и сделать форк к себе.

Настройка рабочей среды

две указанные ниже команды необходимо выполнять каждый раз при входе на рабочую машину (stark/proxima) в домашней директории

setupSCTAU

Выбор базовой сборки

asetup SCTauSim,master,latest

Если вы точно не знаете какую базовую сборку использовать, проконсультируйтесь с координаторами разработки ПО

Настройка git для правильного учёта авторства коммитов (делается один раз)

В начале выполнить команду

git sctau init-config

убедиться, что предлагаемые настройки не ломают ваши прежние, по умолчанию там всё достаточно разумно, и их можно использовать как есть.

Далее применить эти настройки

git sctau init-config --apply

Настройка рабочей директории

Для разработки нового или модификации существующего кода нужны следующие действия:

в домашней директории (на stark/proxima) создадим рабочую область

mkdir workarea
cd workarea

Директории для сборки и запуска

mkdir build  run

Подготовка рабочей директории (делается один раз):

git sctau init-workdir ssh://git@git.inp.nsk.su/sctau/aurora.git

Перейдём в рабочую директорию

cd aurora

Получение обновлений с головного репозитория нужно делать перед созданием каждой новой тематической ветки при длительном существовании рабочей директории

git fetch upstream

Создание рабочей тематической ветки, эта ветка будет видна другим людям, поэтому название следует выбирать говорящим и осмысленным

git checkout -b <TopicDevelopmentBranch> upstream/<target_branch> --no-track

Строчка выше намеренно сделана не рабочей при прямом копировании, выбор целевой ветки важный шаг, поэтому если вы не уверены куда предполагается вносить ваши изменения проконсультируйтесь с координаторами разработки ПО

Для модификации существующего пакета добавим его из репозитория

git sctau addpkg GenExamples

и/или

git sctau addpkg G4SimExamples

Если создаётся новый пакет, то надо создать всю структуру директорий, где он должен лежать, написать CMakeLists.txt и всё остальное, что нужно для нового пакета.

Перед созданием нового пакета проконсультируйтесь с координаторами разработки ПО на тему именования и размещения нового пакета

Кроме того, для управления пакетами в рабочей директории будут полезны следующие команды:

Получение списка пакетов в локальной рабочей директории

git sctau listpkg

Получение списка пакетов во всём репозитории

git sctau listpkg --all

или с фильтрацией по регулярному выражению

git sctau listpkg --all 'Det'
git sctau listpkg --all '/G4.*U'

Удаление пакета из локальной рабочей директории (в репозитории всё остаётся)

git sctau rmpkg <PackageName>

В целом рекомендуется в рабочей директории держать только те пакеты с которыми ведётся работа в настоящий момент, а остальные из рабочей директории убирать

Сборка и запуск

Сборка

cd ../build/
cmake ../aurora/Projects/WorkDir
make

Настройка локального окружения

эта строчка принципиально важна, чтобы использовались локально собранные пакеты вместо тех, что в релизе:

source x86_64-slc7-gcc7-opt/setup.sh

Запуск

cd ../run

Запуск первичных генераторов моделирования:

ctaurun GenExamples/evtgen.py 

Запуск полного моделирования:

ctaurun G4SimExamples/fullsim_example.py

Сохранение изменений

Добавление изменённых файлов

git add ...

или для удаления ненужных более файлов

git rm ...

Фиксируем изменения в локальном репозитории

git commit -m 'Сообщение в котором достаточно подробно полными предложениями описаны сделанные изменения'

Каждый коммит должен содержать минимальный набор логически самодостаточных изменений.

В процессе решения задачи коммитов может быть и чаще всего бывает много

Отправляем наработки на сервер

git push

При первом выполнении этой команды на ветке она завершится с ошибкой, git посоветует с использовать команду вида

git push --set-upstream origin <TopicDevelopmentBranch>

совету надо последовать.

Далее, выполнив команду отправки, git покажет ссылку, открыв которую можно создать запрос на добавление ваших наработок в общий репозиторий (Merge Request)

При создании запроса на добавление ваших наработок убедитесь, что:

• вы отправляете изменения в корректную ветку, это должна быть ветка от которой вы стартовали вашу тематическую
• вы предоставили хорошее описание сделанных изменений
  • кратко разъяснены причины сделанных изменений
  • описаны сами сделанные изменения
  • описаны возможные побочные эффекты и влияние на другие части программного обеспечения
  • указаны ссылки связанные на задачи в gitlab (issues), если такие имеются