Before making any merge request, please make sure you have run the appropriate tests for the release (git branch) which you are targetting. For instance, for the tier-0 release you need to respect the frozen tier 0 policy and run the
RunTier0Tests.py script. For all releases you should explain what tests you have run when making the merge request (see below).
When you push to GitLab, you’ll get several prompts to create a merge request, both at the command line and when you open the project browser. You should ignore these: GitLab will very slow because it will assume you want to merge with master and find a huge number of changes. Fortunately there’s a shortcut to avoid this! You can instead select the “merge requests” button on the left tab:
From here you can create a new merge request
A page now opens that allows you to define the merge request. There are a few points you should pay attention to.
Target branchis correct. This is set by default to
master, but if your merge is not for the Athena development branch you must change it. (A useful cross check is to see how many
Changesare in your merge request - if it’s far more than you expected then the target branch is probably wrong.)
Descriptionare taken from the last commit message of the topic branch. Please edit these to ensure that these fields correctly describe the merge to the person who will review the code
Titlewith a topic, e.g.
MyPackage: ...if your changes only affect one package.
(Here we show a different merge request, but the principle is all the same.)
Before submitting the merge request, you may want to briefly consult the checklist for the review shifters. Make sure that you have taken into account all points to ensure a fast and smooth review process.
Once you are happy with the merge request just press the
Submit merge request
If you are just doing the tutorial as an exercise then please do not actually submit a dummy merge request, just stop here!
After this happens the merge request page on the main repository will open up:
(Note that that screen shot was taken after the continuous integration system had run - initially many of the fields and labels will be blank.)
By default, all MRs are squashed. You can read more about it here, but the basic idea is the commits you made when developing the MR are compressed into one final commit (and you will might want to edit this commit message, to make sure it is informative and complete). If your commits are well factorised and not too numerous, then you can choose to deselect the ‘squash’ option. However, the final decision about whether to squash or not is the release coordinator, whose job it is to keep the repository commit history clean and comprehensible.
ATLAS uses GitLab labels to guide the process of reviewing and handling merge requests. As the developer you have input into this process - by setting appropriate labels on your request you ensure that it is handled correctly by the reviewers and release coordinators.
Note that most labels will just be set automatically by the continuous integration system. Here we list the ones that you might need to set by hand:
|urgent||This merge request fixes something that is high priority, it will jump the queue for review|
|frozen-tier0-violating||This merge request changes the output from Tier-0 and as such requires special attention from PROC (see the twiki for FT0 policy)|
|bugfix||Informs the reviewers and release coordinators that this request fixes an undesired behaviour which may need to be followed up on|
|alsoTargeting:branch||Tells the nightly sweep script that the merge request should be cherry-picked to the branch specified in the label in addition to any other sweeps.|
|sweep:ignore||When targeting a production branch, this merge request will not be cherry-picked to the
For the last label it helps to explain how ATLAS manages code changes that are made to production branches. As ATLAS has to maintain many long lived branches that may be far behind the latest developments in the master branch, we do not follow the standard GitLab Flow workflow in one respect: fixes can be made directly to production branches, because in many cases the fix really has to be different because of framework changes, EDM changes or physics code improvements made to master.
Synchronising changes between the production branches and the master branch then becomes troublesome as in certain cases the fixes are compatible, in certain cases not. And in no case is is possible to merge the master and production branches together (which is git’s more natural way to handle this situation).
So ATLAS runs a script on most production branches that takes accepted
merge requests and tries to cherry-pick these changes onto the master
branch. If the merge would succeed without a conflict then a new
merge request is created (triggering the normal CI and review
process) and the label
sweep:done is added to the MR.
If it would not then the label
sweep:failed is also added.
If, as a developer you know in advance that the merge request you have created
cannot be moved to the master branch then set the
sweep:ignore label. This
will tell the cherry picking script to ignore this merge request.
Note that the terminal state of all production branch merge requests
is one of
sweep:done. If your merge request gets labelled
sweep:failed you must take action:
If the change should
be moved to the master branch then adapt the patch and create a new merge
request. One useful workflow is to make a new branch from of master, then execute
git cherry-pick -m 1 XXX, where
XXX is the commit hash of the merge
(accessible from the merge request page;
-m 1 simply refers to the first of
the two parents in the merge). This will identify the cause of the conflict,
allowing you to use git’s conflict resolutions tools such as
git mergetool -t meld
to fix the conflicts.
If the change should just be ignored, make a comment to that effect on the original merge request.
In both cases, unset the
sweep:failed label and set the
signalling that the situation is resolved.
If you need to update a merge request (for example in response to a request from the review shifter), simply push to the same branch again after editing (and testing) the files.