Workflow Overview¶

Introduction¶

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.

Reminder: one time steps¶

You only need to do these steps once, but for completeness we remind you to:

Check you have done your git environment setup.
Check you have made a fork of the main ATLAS repository.

Warning

One point to reemphasise is make sure that atlasbot is a developer in your fork or continuous integration results are not published properly.

Setup your basic environment¶

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:

ssh lxplus
setupATLAS
lsetup git python

Clone¶

Once you have your fork of the code in GitLab you need to make a local copy to work with and modify.

Cloning to AFS is slow, so if you have an alternative then we recommend that (e.g., a private local disk area, or even $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.

cd athena
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.

Branch¶

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

The correct [target_branch] really depends on the development you are undertaking. If it is for future development, then it is main, if it is for the Tier-0 or HLT it is 24.0. If you are not sure then please ask.

Warning

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!

Development¶

Using your favourite editor and tools make appropriate code changes, making sure you follow the ATLAS coding rules!

Compiling and testing¶

Setup base release¶

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.,

cd ..
asetup Athena,main,latest

Here we setup the Athena project of the latest available nightly in the main branch.

Compile¶

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 ../package_filters.txt
$EDITOR ../package_filters.txt
cmake -DATLAS_PACKAGE_FILTER_FILE=../package_filters.txt ../athena/Projects/WorkDir
make -j

Info

During the build (make) we are executing code quality tools, which may print additional warnings, i.e.:

Cppcheck to detect bugs and and dangerous coding constructs in C++ code.
The CheckerGccPlugins to enforce ATLAS coding conventions and thread-safety in C++ code.
flake8 together with some ATLAS-specific plugins for Python code.

The warnings should be self-explanatory and need to be fixed before submitting your code.

Run and test¶

Setup your local build area in your environment:

source x86_64-el9-gcc14-opt/setup.sh

Now run tests of your code and any tests necessary for your target branch (e.g., frozen Tier-0 tests). At the minimum run the unit tests of your locally checked out packages using:

ctest -j

Review your changes¶

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.

Make a local commit of your changes¶

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:

git commit

Write a good commit message and remember that ChangeLog files are not used anymore.

Push your changes up to GitLab¶

git push -u origin my-topic

Make a merge request¶

Go to the branch overview page on your fork by choosing Repository -> Branches in the top menu. Then select the Merge Request button next to your new branch.

GitLab merge request button

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.

GitLab merge request interface

Continuous integration and code review¶

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.

Code accepted¶

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.