DOC Add documentation about repository management

en/12_Project_Governance/09_Repository_Management.md

@@ -0,0 +1,58 @@
+---
+title: GitHub repository management
+summary: Information about management of the various GitHub repositories
+iconBrand: github
+---
+
+# GitHub repository management
+
+This document outlines the rules and processes for managing the GitHub repositories for supported modules.
+
+## Branches
+
+### Naming convention
+
+Branches with a single integer (e.g. `5`) represent either the next *major* release (if there have been no tagged releases for that release line yet) or the next *minor* release.
+
+Branches with an integer, a dot, and another integer (e.g. `5.2`) represent either the *next patch release* for the current minor, or a patch release for a previous minor version.
+
+> [!NOTE]
+> Branches with any other naming strategy should not be the target of any pull requests. Only branches following this naming convention are included in merge-ups and are used as the base for new tagged releases.
+
+For example, if we have the following tags:
+
+```text
+5.1.17
+5.2.0
+```
+
+Then:
+
+- `5.1` is the patch release branch for the previous minor version. High severity security fixes should target this branch.
+- `5.2` is the next-patch release branch for the current minor version. Bugfixes should target this branch.
+- `5` is the next-minor release branch. Enhancements should target this branch.
+- `6` is the next-major release branch. Changes that break backwards compatibility should target this branch.
+
+### Branch protection
+
+TODO!!!!
+    Individuals who need direct push/tag access are identified and documented.
+    To the extent that exceptions are required, a process is defined for documenting and approving these exceptions.
+        Staff members who do regular direct push (e.g. people doing debugging merges ups) may retain direct push access.
+    Access level of core committers and CMS Squad members are reviewed with a view to disallowing direct push access.
+    Branch protection process and rules are documented and apply only to branches following semantic visioning.
+    The technical process for setting up branch protection is documented.
+    All the documents above are documented in the developer docs.
+    Relevant security policies in our internal Confluence are updated to point to the public doc (to discuss with CISO)
+
+The use cases for access to directly push to branches (as opposed to using a pull request) are:
+
+1. Manually resolving merge conflicts for a merge-up between branches. Our CI pipeline automatically merges up commits between branches, but occasionally will encounter a merge conflict which needs to be manually resolved, committed, and pushed.
+
+The use cases for access to push tags are:
+
+1. Tagging a new minor release. We use a tool to help with this process, but the person using the tool still needs access to push the tag with their GitHub account.
+1. Tagging a new major release. This is effectively the same process as tagging a new minor release.
+
+
+Our CI pipeline includes a process which automatically tags patch releases on patch-release branches if there are commits which warrant a tag. In theory there should be no reason for someone to manually tag a patch release for a supported module. If CI mistakenly thinks there are no commits which warrant a patch release, the logic for checking commits should be updated and CI should be rerun against that branch.