Mantid Git Workflow


This page describes the workflow used in conjunction with Git and GitHub for those who have push access to the repository.

Go here for a cheatsheet of Git commands.

Go here for a (fairly) comprehensive guide to solving your various Git problems.


We follow the GitHub flow, using branches for new work and pull requests for verifying the work.

The steps for a new piece of work can be summarised as follows:

  1. Push up or create an issue here
  2. Create a branch from master, using the naming convention described at Public and Private Branches
  3. Do the work and commit changes to the branch. Push the branch regularly to GitHub to make sure no work is accidentally lost
  4. When you are finished with the work, ensure that all of the unit tests, documentation tests and system tests if necessary pass on your own machine
  5. Open a pull request (Pull Requests) from the GitHub branches page
    • This will check with the buildservers for cross-platform compatibility
    • If any issues come up, continue working on your branch and push to GitHub - the pull request will update automatically

Public and Private Branches

When naming public branches that will be pushed to GitHub, please follow the convention of issuenumber_short_description. This will allow others to discover what the branch is for (issue number) and quickly know what is being done there (short description). Please remember that public branches should not be rebased.

For private branches please follow the convention yourname/issuenumber_short_description. You can sync these with GitHub (for backup reasons) and rebase. Since the branch name is prefixed with your name people will know, by convention, that it is a private branch and can be rebased, deleted, etc at the owner’s whim. Changing a private branch is done by simply renaming the branch to drop the prefix.

Pull Requests

For an general overview of using pull requests on GitHub look here.

When creating a pull request you should:

  • Ensure that the title succinctly describes the changes so it is easy to read on the overview page
    • The title should not contain the issue number
  • Reference the issue which the pull request is closing, using one of these keywords
  • State the user and facility (if relevant) who initiated the original issue, if they are named in the issue. Please do not put full email addresses on the Pull Request, as it is publicly accessible. If the user would not be easily identified by someone picking up the ticket, be prepared to act as a point of contact with the reporter.
  • Ensure the description follows the format described by the PR template on GitHub

A good example is here.

Recommended reading: How to Write the Perfect Pull Request

For further information about the review process see reviewing a pull request.

Checkout a Pull Request

To check out a particular pull request for functional testing use the following commmands:

git fetch <main-remote-name>  +pull/<ID>/merge:pr/<ID>-merged
git checkout pr/<ID>-merged

where <ID> is the pull request number given on GitHub and <main-remote-name> is the name of the remote pointing to the original mantid repository. If you cloned directly from mantid then main-remote-name=origin else if you cloned from a fork then it is the name of remote that points back to the original repository.

Note that these commands will checkout a temporary branch that has the development branch merged with master and not just the development branch on its own. This command can be aliased by adding the following to the [alias] section of your ~/.gitconfig file:

test-pr="!f() { git fetch <main-remote-name> +pull/$1/merge:pr/$1-merged && git checkout pr/$1-merged; }; f"

where again <main-remote-name> has the same meaning as above. A given pull request can now be checkout with

git test-pr <ID>

where <ID> is the pull request number given on GitHub.

Stale Pull Requests

Pull requests that go an extended period of time without any activity are considered stale and will be picked up by a (partially) automated bot which will notify those that are required to take action in order to keep the review process going.

This is also used to notify developers of pull requests that develop conflicts with the base branch and that fail continuous integration tests, in those two cases the age of the pull request is ignored.

The reasons a pull request may be flagged up currently are:

  • Conflicts with base branch
  • Failing CI
  • Last developer has left the Mantid team
  • Nobody has reviewed the PR
  • An assigned reviewer has yet to complete a review
  • A gatekeeper has not second reviewed an approved PR
  • A review from a specific user was requested but that user has yet to complete a review
  • The developer has yet to act on comments left in a review

(code for the bot is currently here)

Code Freeze

At the start of a code freeze before a major release there will be a release branch created named release-next. At this point only bugfixes should be applied to this release branch so that it can be stabilized for the release. The release branch will be merged to master periodically so bugfixes do not need to be separately merged to master.

New Branches

During the code freeze it is important to ensure that a new branch is created from the correct base branch depending on the scope of the changes:

  • master: maintenance fixes, new features. Command: git fetch -p && git checkout --no-track -b MYBRANCH_NAME origin/master
  • release-next: bugfixes. Command: git fetch -p && git checkout --no-track -b MYBRANCH_NAME origin/release-next

Pull Requests

To merge code with the release branch, open a pull request as usual but instead of using the default merge target select release-next:


Fixing a PR with an Incorrect Base Branch

The target branch on GitHub needs to match the base branch used in the commands above when the branch was initially created. If the compare view shows changes other than your own it is most likely that the base branch is incorrect and it needs to be fixed.

As an example consider the scenario where a branch named topic has been based off the master branch as follows:

o---o---o---o---o  master
   |           \
   |            o---o---o  topic
     o---o---o---o---o  release-next

where we actually want the topic branch based off release-next instead i.e.

o---o---o---o---o  master
     o---o---o---o---o  release-next
                              o'---o'---o'  topic

To fix this situation we use the rebase command, providing the --onto option as follows:

git fetch
git rebase --onto origin/release-next origin/master topic