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:

1. Check you have done your git environment setup.
2. 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'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.

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 21.0,r2017-04-07,Athena

Here we setup 21.0 (the branch name), r2017-04-07 (the date the build was started) and Athena (the built project).

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

Run and test

Setup your local build area in your environment:

source x86_64-slc6-gcc62-opt/setup.sh

Now run tests of your code and any tests necessary for your target branch (e.g., frozen Tier-0 tests).

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.

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.

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.