Workflow quick reference

From Charm-Tau Detector
(Difference between revisions)
Jump to: navigation, search
Line 1: Line 1:
−
== Регистрация и подготовка аккаунта ==
+
== Register and prepare account ==
−
* Зарегистрироваться на BINP/GCF кластере, для этого необходимо обратиться к [[User:A.M.Suharev|Андрею Сухареву]] или [[User:D.A.Maksimov‏|Дмитрию Максимову]]
+
* Register at BINP/GCF cluster. Address to [[User:A.M.Suharev|Andrey Sukharev]] or [[User:D.A.Maksimov‏|Dmitry Maximov]]
  
−
* Зайти на <code>stark.inp.nsk.su</code> (доступно только внутри института) или <code>proxima.inp.nsk.su</code> (доступно из любого места)
+
* Log in to <code>stark.inp.nsk.su</code> (BINP local access only) or <code>proxima.inp.nsk.su</code> (accessible from the Internet, pubkey authentication only)
  
−
Эти машины близки по конфигурации и имеют общий <code>/home</code>
+
The login servers have similar configuration and share common <code>/home</code>.
  
−
Для взаимодействия с <code>git</code>-сервером используется протокол <code>ssh</code> с авторизацией по ключам.
+
The <code>git</code> is accessible using <code>ssh</code> protocol with key authorization.
  
−
* Если ранее не был создан, то создать <code>ssh</code> ключ командой
+
* If necessary, create <code>ssh</code> key using
 
  ssh-keygen
 
  ssh-keygen
  
−
согласиться со всеми предлагаемыми по умолчанию ответами на вопросы, ключ можно создавать без пароля.
+
Agree to everything, passwordless keys are allowed.
  
−
В результате в поддиректории <code>~/.ssh/</code> будут созданы два файла <code>id_rsa</code> и <code>id_rsa.pub</code>
+
Then you'll have in your <code>~/.ssh/</code> two files <code>id_rsa</code> and <code>id_rsa.pub</code> - these are your private and public keys.
−
Полные пути к создаваемым файлам будут отображены на экране.
+
Full paths to the files are displayed in the terminal.
  
−
* Зайти на сервер <code>gitlab</code> https://git.inp.nsk.su/ (логин и пароль теже, что и для входа на <code>stark</code>/<code>proxima</code>)
+
* Log in to <code>gitlab</code> server https://git.inp.nsk.su/ using the same name/password as for <code>stark</code>
−
* Зарегистрировать '''публичную''' часть этого ключа в своём аккаунте, т.е. поместить содержимое файла ~/.ssh/id_rsa.pub в форму по ссылке ниже
+
* Register your public key for your account: i. e add ~/.ssh/id_rsa.pub contents to a from at the following link
 
  https://git.inp.nsk.su/profile/keys
 
  https://git.inp.nsk.su/profile/keys
  
  
−
== Создние рабочего репозитория (форк) ==
+
== Create working repository (fork) ==
−
Открыть центральный репозиторий
+
Open central repository
 
  https://git.inp.nsk.su/sctau/aurora
 
  https://git.inp.nsk.su/sctau/aurora
  
−
и сделать форк к себе.
+
and make fork.
  
  
−
== Настройка рабочей среды ==
+
== Tune working environment ==
−
две указанные ниже команды необходимо выполнять '''каждый раз при входе''' на рабочую машину (<code>stark</code>/<code>proxima</code>) в домашней директории
+
Each time you log in to a server <code>stark</code>/<code>proxima</code>, you need to
 
  setupSCTAU
 
  setupSCTAU
−
 
−
Выбор базовой сборки
 
 
  asetup SCTauSim,master,latest
 
  asetup SCTauSim,master,latest
 +
The latter one selects the build to use.
  
−
  ''Если вы точно не знаете какую базовую сборку использовать, проконсультируйтесь с координаторами разработки ПО''
+
  ''Ask software coordinators if you're unsure which build to use''
  
−
Настройка git для правильного учёта авторства коммитов (делается один раз)
+
To tune git do once:
  
−
В начале выполнить команду
+
First, do:
 
  git sctau init-config
 
  git sctau init-config
  
−
убедиться, что предлагаемые настройки не ломают ваши прежние, по умолчанию там всё достаточно разумно, и их можно использовать как есть.
+
Check if the settings are correct. But the defaults should be fine.
  
−
Далее применить эти настройки
+
Then apply the settings:
 
  git sctau init-config --apply
 
  git sctau init-config --apply
  
  
−
== Настройка рабочей директории ==
+
== tune working directory ==
−
Для разработки нового или модификации существующего кода нужны следующие действия:
+
To develop new code or to modify existing one, do:
  
−
в домашней директории (на <code>stark</code>/<code>proxima</code>) создадим рабочую область
+
create workare in your home directory (at <code>stark</code>/<code>proxima</code>)
 
  mkdir workarea
 
  mkdir workarea
 
  cd workarea
 
  cd workarea
  
−
Директории для сборки и запуска
+
create directories for build and run:
 
  mkdir build  run
 
  mkdir build  run
  
−
Подготовка рабочей директории (делается один раз):
+
workarea preparation (just once):
 
  git sctau init-workdir ssh://git@git.inp.nsk.su/sctau/aurora.git
 
  git sctau init-workdir ssh://git@git.inp.nsk.su/sctau/aurora.git
  
−
Перейдём в рабочую директорию
+
Go to working directory
 
  cd aurora
 
  cd aurora
  
−
Получение обновлений с головного репозитория нужно делать '''перед созданием каждой новой тематической ветки''' при длительном существовании рабочей директории
+
Fetch updates from head repository (must be done before '''creating a branch''' when the workarea exists for a long time)
 
  git fetch upstream
 
  git fetch upstream
  
−
Создание рабочей тематической ветки, эта ветка будет видна другим людям, поэтому название следует выбирать говорящим и осмысленным
+
Create a working branch. Give it a sensible name:
 
  git checkout -b <TopicDevelopmentBranch> upstream/<target_branch> --no-track
 
  git checkout -b <TopicDevelopmentBranch> upstream/<target_branch> --no-track
  
  
−
'''Строчка выше намеренно сделана не рабочей при прямом копировании, выбор целевой ветки важный шаг, поэтому если вы не уверены куда предполагается вносить ваши изменения проконсультируйтесь с координаторами разработки ПО'''
+
'''The line above will not work if you simply copy-paste it. It is intentional. It is important to choose correct target branch. If unsure ask software coordinators.'''
  
  
−
Для  модификации существующего пакета добавим его из репозитория
+
To modify an existing package check it out:
 
  git sctau addpkg GenExamples
 
  git sctau addpkg GenExamples
−
и/или
 
−
git sctau addpkg G4SimExamples
 
  
−
Если создаётся новый пакет, то надо создать всю структуру директорий, где он должен лежать, написать CMakeLists.txt и всё остальное, что нужно для нового пакета.
+
To create new package, one should create its whole directory structure, provide CMakeLists.txt and everything.
  
−
  ''Перед созданием нового пакета проконсультируйтесь с координаторами разработки ПО на тему именования и размещения нового пакета''
+
  ''Before creating new package ask software coordinators how to name and where to place it''
  
−
Кроме того, для управления пакетами в рабочей директории будут полезны следующие команды:
+
Useful commands to manage packages in you working area:
  
−
Получение списка пакетов в локальной рабочей директории
+
List local packages
 
  git sctau listpkg
 
  git sctau listpkg
  
−
Получение списка пакетов во всём репозитории
+
List packages in the whole repository
 
  git sctau listpkg --all
 
  git sctau listpkg --all
−
или с фильтрацией по регулярному выражению
+
or with regexp filter
 
  git sctau listpkg --all 'Det'
 
  git sctau listpkg --all 'Det'
 
  git sctau listpkg --all '/G4.*U'
 
  git sctau listpkg --all '/G4.*U'
  
  
−
Удаление пакета из локальной рабочей директории (в репозитории всё остаётся)
+
Remove local package (the repository left intact)
 
  git sctau rmpkg <PackageName>
 
  git sctau rmpkg <PackageName>
  
−
В целом рекомендуется в рабочей директории держать только те пакеты с которыми ведётся работа в настоящий момент,
+
It is recommended to keep locally only the packages under active development.
−
а остальные из рабочей директории убирать
+
  
−
== Сборка и запуск ==
+
== Build and run ==
−
Сборка
+
To build:
 
  cd ../build/
 
  cd ../build/
 
  cmake ../aurora/Projects/WorkDir
 
  cmake ../aurora/Projects/WorkDir
 
  make
 
  make
  
−
Настройка локального окружения
+
To setup local environment (to use locally built packages instead of default versions):
−
 
+
−
эта строчка принципиально важна, чтобы использовались локально собранные пакеты вместо тех, что в релизе:
+
 
  source x86_64-slc7-gcc7-opt/setup.sh
 
  source x86_64-slc7-gcc7-opt/setup.sh
  
−
Запуск
+
To run
 
  cd ../run
 
  cd ../run
  
−
Запуск первичных генераторов моделирования:
+
Run primary generators:
 
  ctaurun GenExamples/evtgen.py  
 
  ctaurun GenExamples/evtgen.py  
  
−
Запуск полного моделирования:
+
Run ull simulation:
−
 
+
 
  ctaurun G4SimExamples/fullsim_example.py
 
  ctaurun G4SimExamples/fullsim_example.py
  
−
== Сохранение изменений ==
+
== Commit changes ==
−
Добавление изменённых файлов
+
In the 'aurora' directory:
−
git add ...
+
  
−
или для удаления ненужных более файлов
+
Add changed files
−
  git rm ...
+
  git add <list of files>
  
 +
remove unnecessary files
 +
git rm <list of files>
  
−
Фиксируем изменения в локальном репозитории
 
−
git commit -m 'Сообщение в котором достаточно подробно полными предложениями описаны сделанные изменения'
 
  
−
Каждый коммит должен содержать минимальный набор логически самодостаточных изменений.
+
Commit changes in the local repository:
 +
git commit -m 'Meaningful message concerning the introduced changes'
  
−
В процессе решения задачи коммитов может быть и чаще всего бывает много
+
Each commit should contain a minimal set of logically interconnected changes.
 +
You may (and will) have many commits when developing a package.
  
−
Отправляем наработки на сервер
+
Put the changes to the server:
 
  git push
 
  git push
  
−
При первом выполнении этой команды на ветке она завершится с ошибкой, <code>git</code> посоветует с использовать команду вида
+
Wheh doing push for the first time, it is necessary to do it like
 
  git push --set-upstream origin <TopicDevelopmentBranch>
 
  git push --set-upstream origin <TopicDevelopmentBranch>
  
−
совету надо последовать.
 
  
−
Далее, выполнив команду отправки, <code>git</code> покажет ссылку, открыв которую можно создать запрос на добавление ваших наработок в общий репозиторий (<code>Merge Request</code>)
+
After the push, <code>git</code> displays a link to be followed for a <code>Merge Request</code> (adding your contributions to common repository).
  
−
При создании запроса на добавление ваших наработок убедитесь, что:
+
When doing a merge request, make sure:
−
* вы отправляете изменения в корректную ветку, это должна быть ветка от которой вы стартовали вашу тематическую
+
* the branch is correct
−
* вы предоставили хорошее описание сделанных изменений
+
* changes are well described
−
** кратко разъяснены причины сделанных изменений
+
** reasons for the changes are demonstrated
−
** описаны сами сделанные изменения
+
** the changes are described
−
** описаны возможные побочные эффекты и влияние на другие части программного обеспечения
+
** influence on the other software and possible side effects are indicated
−
** указаны ссылки связанные на задачи в <code>gitlab</code> (<code>issues</code>), если такие имеются
+
** there are links to related issues, if any
  
  
 
[[Category:Not_public]][[Category:Software]]
 
[[Category:Not_public]][[Category:Software]]

Revision as of 17:30, 4 October 2019

Contents

Register and prepare account

  • Log in to stark.inp.nsk.su (BINP local access only) or proxima.inp.nsk.su (accessible from the Internet, pubkey authentication only)

The login servers have similar configuration and share common /home.

The git is accessible using ssh protocol with key authorization.

  • If necessary, create ssh key using 
ssh-keygen

Agree to everything, passwordless keys are allowed.

Then you'll have in your ~/.ssh/ two files id_rsa and id_rsa.pub - these are your private and public keys. Full paths to the files are displayed in the terminal.

  • Log in to gitlab server https://git.inp.nsk.su/ using the same name/password as for stark
  • Register your public key for your account: i. e add ~/.ssh/id_rsa.pub contents to a from at the following link 
https://git.inp.nsk.su/profile/keys


Create working repository (fork)

Open central repository 

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

and make fork.


Tune working environment

Each time you log in to a server stark/proxima, you need to 

setupSCTAU
asetup SCTauSim,master,latest

The latter one selects the build to use. 

Ask software coordinators if you're unsure which build to use

To tune git do once:

First, do: 

git sctau init-config

Check if the settings are correct. But the defaults should be fine.

Then apply the settings: 

git sctau init-config --apply


tune working directory

To develop new code or to modify existing one, do:

create workare in your home directory (at stark/proxima) 

mkdir workarea
cd workarea

create directories for build and run: 

mkdir build  run

workarea preparation (just once): 

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

Go to working directory 

cd aurora

Fetch updates from head repository (must be done before creating a branch when the workarea exists for a long time) 

git fetch upstream

Create a working branch. Give it a sensible name: 

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


The line above will not work if you simply copy-paste it. It is intentional. It is important to choose correct target branch. If unsure ask software coordinators.


To modify an existing package check it out: 

git sctau addpkg GenExamples

To create new package, one should create its whole directory structure, provide CMakeLists.txt and everything. 

Before creating new package ask software coordinators how to name and where to place it

Useful commands to manage packages in you working area:

List local packages 

git sctau listpkg

List packages in the whole repository 

git sctau listpkg --all

or with regexp filter 

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


Remove local package (the repository left intact) 

git sctau rmpkg <PackageName>

It is recommended to keep locally only the packages under active development.

Build and run

To build: 

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

To setup local environment (to use locally built packages instead of default versions): 

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

To run 

cd ../run

Run primary generators: 

ctaurun GenExamples/evtgen.py

Run ull simulation: 

ctaurun G4SimExamples/fullsim_example.py

Commit changes

In the 'aurora' directory:

Add changed files 

git add <list of files>

remove unnecessary files 

git rm <list of files>


Commit changes in the local repository: 

git commit -m 'Meaningful message concerning the introduced changes'

Each commit should contain a minimal set of logically interconnected changes. You may (and will) have many commits when developing a package.

Put the changes to the server: 

git push

Wheh doing push for the first time, it is necessary to do it like 

git push --set-upstream origin <TopicDevelopmentBranch>


After the push, git displays a link to be followed for a Merge Request (adding your contributions to common repository).

When doing a merge request, make sure:

  • the branch is correct
  • changes are well described
    • reasons for the changes are demonstrated
    • the changes are described
    • influence on the other software and possible side effects are indicated
    • there are links to related issues, if any
Retrieved from "https://ctd.inp.nsk.su/wiki/index.php?title=Workflow_quick_reference&oldid=766"
Personal tools