Make a Merge Request

Last update: 05 Jul 2023 [History] [Edit]

Testing

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

Start a merge request

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 main 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

Define the request

A page now opens that allows you to define the merge request. There are a few points you should pay attention to.

  • Check that the Target branch is correct. This is set by default to main, but if your merge is not for the Athena development branch you must change it. (A useful cross check is to see how many Changes are in your merge request - if it’s far more than you expected then the target branch is probably wrong.)

  • The Title and Description are 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
    • it’s your job to convince them that this change is well motivated and well implemented! List the tests that you have run.
    • It is a good convention start the Title with 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 button.

Warning 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.)

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

Add labels

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 urgent label This merge request fixes something that is high priority, it will jump the queue for review
frozen-tier0-violating FT0 label This merge request changes the output from Tier-0 and as such requires special attention from PROC (see the twiki for FT0 policy)
bugfix bugfix label Informs the reviewers and release coordinators that this request fixes an undesired behaviour which may need to be followed up on
alsoTargeting:branch also targeting label 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 sweep ignore label When targeting a production branch, this merge request will not be cherry-picked to the main branch.

Cherry picking (a.k.a. sweeps)

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

Synchronising changes between the production branches and the main 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 main 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 main 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 main 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:ignore or sweep:done. If your merge request gets labelled as sweep:failed you must take action:

  • If the change should be moved to the main branch then adapt the patch and create a new merge request. One useful workflow is to make a new branch from of main, 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 sweep:ignore one signalling that the situation is resolved.

Revise a merge request

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.