These instructions are not intended to be a complete guide to using git and
GitHub. For more general information, please see the GitHub Docs and the Met Office
Git and GitHub documentation.
Contributors should fork the relevant repository (ANTS, UG-ANTS,
ancillary-file-science, ug-ancillary-file-science) on GitHub and create a
branch in this fork.
Branch names should start with the issue number, e.g.
<issue-number>-descriptive-branch-name. Often it is convenient to use the
GitHub web interface to create the branch from the issue page. Click Createabranch and select your fork as the repository destination. Check out the new
branch locally using gitcheckout<branch-name>.
Commit messages should start with the issue number for the branch e.g.
#<issue-number>Descriptivemessage.... This generates links back to
the issue when viewing the branch history in GitHub. Other issues can be
referenced in the commit message as needed.
Every commit made with the assistance of Generative AI tools need to be
flagged in the commit message. The second line of the commit should be blank,
but the third line should be:
Some of the content of this commit has been produced with the assistance of <Generative AI tool name>
Verbose commit messages are encouraged since they can aid the reviewer if they
can see the approaches that were attempted and rejected.
Code is merged to the main branch via a pull request (PR) on GitHub. When
your changes are ready for review, open a PR from your branch to the main
branch of the relevant repository. Fill in the PR template as completely as
possible to aid the reviewer, including Closes#<issue-number> to link the
PR to the issue it addresses. Please give your PR a descriptive title of the
change being provided as the PR title is what will be used to generate release
notes e.g. rather than “Land Tiles” use “Add new Land Tile types”.
Once a PR is opened, a set of GitHub actions will run, including unit tests,
code style checks, and building the documentation. These checks must all be
passing by the end of the review process before the PR can be merged.
Note
Some repositories contain a “CI Path Checks” action. This will fail if paths
have been added as part of a PR. This is expected where a change involves
new source or KGO files being added to rose-stem workflows and serves as a
reminder to your reviewer that they need to be removed before merging to
main. Typically, your reviewer will handle getting this action to pass as the
last step in the review process.
Tip
You may also wish to open a draft pull request earlier in the development
process prior to requesting a full review. This allows others to see the
work in progress and provide early feedback if desired.
When you are ready for your change to be reviewed by the ANTS team with a view
to merging to main, please email the miao@metoffice.gov.uk inbox with “Review
Request” in the title. Only PRs that have a review requested in this way
will be assigned for technical review by the ANTS team.
Please do not assign reviewers yourself.
The aim of the review is to improve the code by making it more maintanable,
supportable and robust. If you prefer a different approach to meet these goals
than the approach suggested by a reviewer, please do suggest it. The review is
a conversation not a mandate from the reviewer. In that spirit, most review
comments are suggestions rather than requirements.
Code can be submitted for a preliminary review to check that it is on the right
path - in this circumstance, please let the reviewer know what code should be
being examined.
Similarly, if there’s code that the developer thinks could benefit from extra
scrutiny (e.g. using a library where the developer has less confidence),
informing the reviewer will help them to prioritise their effort.
Please do not approach individual staff who may be working on ANTS.
Working with your reviewer during the code review process#
A typical code review involves back and forth between a developer and reviewer.
The activity on a PR can become busy very quickly, so this section outlines ways
you can help make this process as streamlined as possible for all involved.
If you have made changes in response to a review and are ready for them to
take a look, click the “Re-request review” button next to the reviewer’s name in
the Reviewers section.
A review will often involve a reviewer adding comments in the form of a
“conversation” against your code. If you address/reply to these as part of the
review process, please leave it to the reviewer to “Resolve conversation”. This
helps your reviewer keep track of what they asked at the previous review
iteration. In the case where you apply a “suggestion” from a reviewer, the
conversation will be resolved automatically. This is fine and you don’t need to
unresolve it.
Similarly, you can make your reviewer’s life easier when reviewing big changes
by breaking down your code changes in response to review into distinct commits.
You can then point your reviewer to them by adding the commit hash to replies
to conversations - these are the alphanumeric links next to where your commits
are listed in the PR which can be copied and pasted into replies. Note, we
understand that there will be cases where it is not sensible or useful to do this,
for instance if you are correcting the same typo in multiple places one commit
is fine rather than an individual commit for each corrected word.
