Documentation for Release 2024.2
Pull Request Strategy
High-level strategy
- Work on a new branch on a single feature that has an associated issue.
- Create a pull request on GitHub.
- When the feature is ready, check that all GitHub actions have passed and request a review.
- Merge pull request when it is approved.
Work on a feature branch
The goal is to keep each pull request narrowly focussed:
- Each pull request should address one feature/bug, or at most a small number of closely-related features/bugs.
- Each pull request should be associated with a GitHub issue.
The rough idea is that every issue’s commits will appear on a
feature branch (branched out from develop
), until the issue is ready to be
closed, and then they’ll be merged back in to develop.
Opening a brand new issue
First, make sure you’ve made a new GitHub issue. This will have a number, let’s
say XXXX
. So the git branch can be called, for example,
XXXX_issue_description
. Wherever you see XXXX
below, replace it with the
number of your issue! The branch will eventually be deleted, so the name of the
branch is not hugely important; but aim for something short and descriptive.
Note: only do this if the issue has never been worked on before, and an
<XXXX_issue_description>
branch doesn’t exist in the main repository already.
If you haven’t just opened the GitHub issue so you aren’t sure whether it
exists, you can type:
git branch -a
which will display all local and remote branches that are available. If
<XXXX_issue_description>
does exist, skip down to the
next section.
Local repo
When you start work on a new issue, you first need to create a branch on your local repository, as discussed here. If instead you want to use a pre-existing feature branch that’s on the Chaste repo, see below.
You can pass the -b
flag to the git checkout
command to create and
switch to a new branch in one action:
git checkout -b <XXXX_issue_description> develop
To list all the available (local) branches:
git branch
Remote repo
If you’ve made a new feature branch locally, you should then immediately make a copy of that on the central Chaste git repository, so do:
# Just makes sure the branch you want to push is the one currently checked out locally.
git checkout <XXXX_issue_description>
# Push a copy to the main Chaste repo. <remote> is probably just = origin.
# The -u should make git track the pushed branch as the new remote.
git push -u <remote> <XXXX_issue_description>
This will make a copy, with the same name, on the main Chaste repo that other people can work on too, by checking it out as below.
Working on a pre-existing issue
If an issue feature branch already exists, and you just want to grab a copy of it on your local repository just do:
git checkout --track <remote>/<branch>
e.g.
git checkout --track origin/<XXXX_issue_description>
Note that after a branch is setup to --track
a remote branch, every subsequent
use of git pull
and git push
with no additional arguments will pull/push
changes between the local and remote branches.
Note for all recent versions of Git (>1.6.6), as long as you have previously fetched the remote branch (run the above commands once), you can simply use
git checkout <XXXX_issue_description>
git pull
Then make all the local commits you need and push them to the server, as above.
Commit messages
To make sure that the GitHub issue references all the relevant commits, all commits to do with your issue should start with the issue number, prefixed with a hash symbol, e.g.
git commit -m "#<XXXX> an informative message describing the changes."
e.g.
git commit -m "#3057 added special case for python3.5 to prevent upgrade of pip to incompatible version."
This means that things are nicely cross-referenced when looking at the timeline and doing detective work!
Create a pull request
Create a pull request using the GitHub user interface. You can create the pull request at any time; you do not need to wait for the feature to be complete.
Each time you push new commits, the GitHub actions will be re-run giving you feedback on the state of compilation/testing.
Getting changes from develop
It probably makes sense to test your code with any changes that have happened in
develop
since you branched off. So get any changes to develop with:
git checkout develop
git pull
Now go to your local issue branch, and merge in these changes
git checkout <XXXX_issue_description>
git pull # Get any changes that other people have done in the meantime!
git merge develop
Sort out any conflicts that arise, and send the change to
XXXX_issue_description
on the remote server with:
git push
Wait for approval
Once the feature is complete and the GitHub actions are all passing, request a review. This can be done via the pull request interface in the right-hand panel. Either choose an appropriate reviewer or ask in Slack for who would be an appropriate reviewer.
Merge pull request
Once the pull request is approved, merge it using the pull request interface. Do not choose the “squash commits” option as this eliminates all intermediate commit history.
After an issue branch passes all tests and is merged into develop
, the last
thing we should do on each issue should be to delete the branches to
keep the repository clean. On GitHub, this can be done from the pull request
interface.
On your local repo,
git branch -d <XXXX_issue_description>
Note this only works if all the changes have been merged into develop
(clever!). If for any reason you have extra local changes, but definitely don’t
want them merging in, you need to use an extra --force
flag.