From 02dbb32f1757ab8226f0aab7557c1a19c221d657 Mon Sep 17 00:00:00 2001 From: Guy Sartorelli Date: Wed, 27 Mar 2024 11:32:44 +1300 Subject: [PATCH] DOC Add documentation about repository management --- .../09_Repository_Management.md | 71 +++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 en/12_Project_Governance/09_Repository_Management.md diff --git a/en/12_Project_Governance/09_Repository_Management.md b/en/12_Project_Governance/09_Repository_Management.md new file mode 100644 index 000000000..5c52b2478 --- /dev/null +++ b/en/12_Project_Governance/09_Repository_Management.md @@ -0,0 +1,71 @@ +--- +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 + +Some actions are restricted to avoid bad actors or accidental mistakes from causing problems. This section outlines the branch protection rules, and who they apply to. + +If any exceptions to these rules need to be made for any reason, each exception must be approved in writing by the Silverstripe CMS Product Owner and only apply for a specified amount of time. + +#### Deleting branches + +A branch protection rule to protect against deleting branches is added by going to `https://github.com/silverstripe//settings/branches`, clicking "Add rule", inputting `[0-9]*` as the branch name pattern, and clicking create (without checking any of the checkboxes). + +Any branches following the documented naming convention cannot be deleted by anyone. + +If a branch following that naming convention is created by mistake, a Core Committer can rename and then delete the branch. + +#### Access for directly pushing commits + +By default, users don't have access to directly push commits unless they are given that permission either directly or by being in a group which has that permission. + +The use cases for access to directly push commits to branches (as opposed to using a pull request) are: + +- 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. + +Senior developers in the CMS Squad and all members of the Core Committers team are given access to directly push commits to supported module repositories. + +#### Access for pushing tags + +By default, users don't have access to push tags unless they are given that permission either directly or by being in a group which has that permission. + +The use cases for access to push tags are: + +- 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. +- 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. + +Senior developers in the CMS Squad and all members of the Core Committers team are given access to push tags to supported module repositories.