.. Some of the content of this file has been produced with the assistance of Met Office GitHub Copilot Enterprise Development process =================== 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 `_. Creating an issue :octicon:`issue-opened` ----------------------------------------- Development starts with the creation of an issue on the relevant repository: .. button-link:: https://github.com/MetOffice/ANTS/issues/new/choose :color: primary :shadow: Create an issue in the ANTS repository .. button-link:: https://github.com/MetOffice/UG-ANTS/issues/new/choose :color: primary :shadow: Create an issue in the UG-ANTS repository .. button-link:: https://github.com/MetOffice/ancillary-file-science/issues/new/choose :color: secondary :shadow: Create an issue in the ancillary-file-science repository .. button-link:: https://github.com/MetOffice/ug-ancillary-file-science/issues/new/choose :color: secondary :shadow: Create an issue in the ug-ancillary-file-science repository .. button-link:: https://github.com/MetOffice/ancillary-file-data-preparation/issues/new/choose :color: secondary :shadow: Create an issue in the ancillary-file-data-preparation repository Please take time to check whether there is an existing issue that covers your requirements before creating a new one. Forking the repository :octicon:`repo-forked` --------------------------------------------- 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. .. button-link:: https://github.com/MetOffice/ANTS/fork :color: primary :shadow: Fork the ANTS repository .. button-link:: https://github.com/MetOffice/UG-ANTS/fork :color: primary :shadow: Fork the UG-ANTS repository .. button-link:: https://github.com/MetOffice/ancillary-file-science/fork :color: secondary :shadow: Fork the ancillary-file-science repository .. button-link:: https://github.com/MetOffice/ug-ancillary-file-science/fork :color: secondary :shadow: Fork the ug-ancillary-file-science repository .. button-link:: https://github.com/MetOffice/ancillary-file-data-preparation/fork :color: secondary :shadow: Fork the ancillary-file-data-preparation repository Clone your fork locally using ``git clone``. Creating a branch :octicon:`git-branch` --------------------------------------- Branch names should start with the issue number, e.g. ``-descriptive-branch-name``. Often it is convenient to use the GitHub web interface to create the branch from the issue page. Click ``Create a branch`` and select your fork as the repository destination. Check out the new branch locally using ``git checkout ``. Making changes :octicon:`pencil` -------------------------------- Make your changes in the branch you have created. Please follow the :ref:`code conventions `, :doc:`licence and attribution `, :doc:`documentation `, and :doc:`testing ` guidelines. Commit messages should start with the issue number for the branch e.g. ``# Descriptive message...``. 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: .. code-block:: none Some of the content of this commit has been produced with the assistance of Verbose commit messages are encouraged since they can aid the reviewer if they can see the approaches that were attempted and rejected. Opening a pull request :octicon:`git-pull-request` -------------------------------------------------- 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 #`` 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. .. _draft pull request: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests 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.