diff --git a/source/WorkingPractices/maintaining_branches.rst b/source/WorkingPractices/maintaining_branches.rst new file mode 100644 index 00000000..b34acdff --- /dev/null +++ b/source/WorkingPractices/maintaining_branches.rst @@ -0,0 +1,242 @@ +.. ----------------------------------------------------------------------------- + (c) Crown copyright Met Office. All rights reserved. + The file LICENCE, distributed with this code, contains details of the terms + under which the code may be used. + ----------------------------------------------------------------------------- + +.. _maintaining_branches: + +Maintaining Branches +==================== + +Simulation Systems repositories use version branches to aid in scientific +evaluation and testing. This means that all new branches should be taken from a +release and should not be updated with the latest changes on ``main`` until +ready to be merged. Exceptions can be made for changes that are specifically +building on changes already merged since the last release. + +Developments that take longer than one release cycle can be upgraded to the +new release when convenient, and should be upgraded before opening a pull +request. + +.. _upgrading_to_release: + +Upgrading to a release and maintaining old version branches +----------------------------------------------------------- + +A common working style for scientific development is to maintain the changes at +multiple different versions, to aid scientific testing. In this case we +recommend working from a main development branch, that is up to date with the +latest release. Branches for previous versions can be created from this +development branch as required. We also recommend using :ref:`tags ` as a +way of providing human-readable labels to individual commits. + +Below is a diagram demonstrating this suggested way of working. + +.. mermaid:: + + --- + config: + theme: neutral + themeVariables: {lineColor: '#58a6ff', fontSize: 10px} + --- + + flowchart TB + classDef dev_branch fill:#8eb6e8,stroke:#5bc0de,stroke-width:2px,color:#000 + classDef tag fill:#a8ffcf,stroke:#57ffa2,stroke-width:2px,color:#000 + classDef vn_branch fill:#ffde91,stroke:#fcc43f,stroke-width:2px,color:#000 + + + create_dev[Create a Development Branch
*new_feature_branch*]:::dev_branch + tag_xy{{Tag Branch Before Upgrading
*tagX.Y_feature_branch*}}:::tag + upgrade_xy1[Upgrade to vnX.Y+1
*new_feature_branch*]:::dev_branch + branch_xy[Create vnX.Y Development Branch
*vnX.Y_feature_branch*]:::vn_branch + develop_xy[Further Develop Changes at vnX.Y
*vnX.Y_feature_branch*]:::vn_branch + tag_xy1{{Tag Branch Before Upgrading
*tagX.Y+1_feature_branch*}}:::tag + retag_xy1{{Update tag to include further changes
*tagX.Y+1_feature_branch*}}:::tag + upgrade_xy2[Upgrade to vnX.Y+2
*new_feature_branch*]:::dev_branch + branch_xy1[Create vnX.Y+1 Development Branch
*vnX.Y+1_feature_branch*]:::vn_branch + develop_xy1[Further Develop Changes at vnX.Y+1
*vnX.Y+1_feature_branch*]:::vn_branch + + + subgraph vnX.Y["vnX.Y Steps"] + create_dev -->|Development Changes| tag_xy + tag_xy --> branch_xy --> develop_xy + end + + subgraph vnX.Y+1["vnX.Y+1 Steps"] + tag_xy --> upgrade_xy1 -->|Development Changes| tag_xy1 + tag_xy1 --> branch_xy1 --> develop_xy1 --> retag_xy1 + tag_xy1 --> retag_xy1 + end + + subgraph vnX.Y+2["vnX.Y+2 Steps"] + tag_xy1 --> upgrade_xy2 + end + + subgraph legend[" "] + direction TB + dev_box[Development Branch]:::dev_branch + vn_box[Versioned Branch]:::vn_branch + tag_box{{Tag Creation}}:::tag + end + +* Create a development branch and develop your new feature on this branch. This + branch will be upgraded to newer versions when required and will be submitted + via a Pull Request. +* When ready to upgrade to a newer version: + + * Create a tag before updating the branch. This allows easy identification of + the pre-updated branch, without needing to read the git log to find the + particular commit. It can be used as the ``ref`` value in + ``dependencies.yaml`` files in rose-stem and standalone suites. See below + for advice about creating tags. + + To aid readability of different refs, we recommend following the naming + scheme ``tagX.Y_dev_branch_name`` where ``X.Y`` is substituted for the + release this tag represents. + * If further development at the previous version is likely, then a version + branch can be created based off the new tag, + ``git switch -c vnX.Y_dev_branch_name tagX.Y_dev_branch_name`` where + ``vnX.Y`` represents that this is now a version branch. As changes are made + to this branch, the associated version tag can be safely updated to point at + the latest commits. + * The main development branch can now be updated to the newest version. This + can be done by running ``git merge stable``, having first ensured the + ``stable`` branch in the fork is up to date with the upstream repository. + More details on this process can be seen :ref:`below `. + +* This process can be repeated across multiple version upgrades, creating tags + and branches for old versions as desired. + +We recommend this process of maintaining a single development branch which moves +to new releases as the source branch of Pull Requests cannot be changed. +Therefore, if the Pull Request spans multiple releases, it doesn't need to be +closed and a new one opened as new branches are created. + +.. important:: + + Do not use ``git rebase`` to upgrade your branch to the latest release. This + rewrites the history of the branch and makes it impossible for suites to + include your changes at a previous release. + +.. admonition:: Tagging + + Tagging gives a human-readable label to a specific commit. You are free + to apply whatever tags you wish within your fork of a repository. + + .. code-block:: + + git tag -a