This page gives you a quick overview of the ATLAS code development workflow. It is assumed that you worked through the main git development tutorial at least once. Please refer back to that if you are not clear on any points.
The workflow that ATLAS has adopted is basically GitLab Flow, which offers enough flexibility to manage ATLAS use cases, but is structured enough to avoid a mess.
You may also find it handy to refer to our git cheat sheet as a quick reference to the most common command and terms.
You only need to do these steps once, but for completeness we remind you to:
One point to reemphasise is make sure that
atlasbotis a developer in your fork or continuous integration results are not published properly.
Assuming that you will work on an lxplus-like machine you want to start the development workflow by setting up decently modern version of git:
lsetup git python
Cloning to AFS is slow, so if you have an alternative then
we recommend that (e.g., a private local disk area, or
$TMDDIR for very short developments).
git clone https://:@gitlab.cern.ch:8443/[YOUR_USER_NAME]/athena.git
Then make sure you can pull updates from the main repository.
git remote add upstream https://:@gitlab.cern.ch:8443/atlas/athena.git
Note, we described the full checkout workflow here. For a sparse checkout please look here.
To start modifying code, create a new branch, starting from the release branch that you are targeting, and giving the branch a meaningful name (e.g., some description of the bug you are fixing or the feature you are adding). You may also find it useful to add the name of the target branch in the name.
git fetch upstream # Ensure sync with main repository
git checkout -b 21.0-fix-muon-alignment upstream/[target_branch] --no-track
[target_branch] really depends on the development you
are undertaking. If it’s for AthenaMT then it is
main, if it is for
the Tier-0 it’s
21.0, if it’s for HLT then it’s
21.1. If you are
not sure then please ask.
Choosing the right target branch is one thing you do have to think about, which is why we made this not work with copy and paste!
Using your favourite editor and tools make appropriate code changes, making sure you follow the ATLAS code rules!
In order to test that your code compiles and runs correctly you will need to setup a pre-built release to work with, adding only your changed packages on top. It’s usually best to setup a recent nightly build of your target branch, e.g.,
Here we setup
21.0 (the branch name),
r2017-04-07 (the date the build was started)
Athena (the built project).
Setup a build area, make a suitable package filter file to only rebuild some of the release, then build:
mkdir build && cd build
cp ../athena/Projects/WorkDir/package_filters_example.txt ../pf.txt
cmake -DATLAS_PACKAGE_FILTER_FILE=../pf.txt ../athena/Projects/WorkDir
Setup your local build area in your environment:
Now run tests of your code and any tests necessary for your target branch (e.g., frozen Tier-0 tests).
It’s always a good idea to let git show you what you changed.
git status # shows which files were modified
git diff # shows how each file's content was changed
Please also now remind yourself of all the points that the merge request shifters will look at and make sure that your merge request conforms to them all.
Add the files you want to commit to the staging area, e.g.,:
git add Foo/Bar/Package/src/MyTool.h
git add Foo/Bar/Package/src/MyTool.cxx
Then commit the changes into your local repository:
Write a good commit message and
ChangeLog files are not used anymore.
git push -u origin my-topic
Go to the branch overview page on your fork by choosing
Branches in the top menu. Then select the
Merge Request button
next to your new branch.
Make sure you are merging to the right target branch (this should
be the target branch from which you started your topic
branch). If GitLab didn’t select the
correct branch use the
Change Branches option to correct it.
Make sure that you enter a good description of your change.
To check your code, the Jenkins continuous integration system will checkout your changes, ensure that they configure and build correctly. The results of these tests will be reported in a comment made in the merge request.
Your code will now be reviewed.
Once the reviewer is happy with your code they will sign off the merge request. The release coordinator for the release concerned will then actually merge in the changes when they are ready to accept them.