Documenting the branching process (#1956)

* resolves #1772 documenting the branching process

* Update README.md

Co-authored-by: Maxwell G <[email protected]>

* Update README.md

Co-authored-by: Felix Fontein <[email protected]>

* updates and suggestions

* update the support matrix section

* Update README.md

Co-authored-by: Maxwell G <[email protected]>

* Update README.md

Co-authored-by: Maxwell G <[email protected]>

* updates and suggestions

* maintainers guide

* rm active branch example

* Update MAINTAINERS.md

Co-authored-by: Sandra McCann <[email protected]>

---------

Co-authored-by: Maxwell G <[email protected]>
Co-authored-by: Felix Fontein <[email protected]>
Co-authored-by: Sandra McCann <[email protected]>

Author: 4 people

MAINTAINERS.md

@@ -0,0 +1,81 @@
+# Maintainers guide
+
+Find details about maintaining the `ansible-documentation` repository.
+Note that maintainers have privileged access to the repository to perform special functions such as branching for new versions and preparing Ansible documentation for publishing.
+If you're interested in becoming a maintainer, or want to get in touch with us, please join us on matrix at [#docs:ansible.im](https://matrix.to/#/#docs:ansible.im).
+We have weekly meetings on matrix every Tuesday (see [the Ansible calendar](https://forum.ansible.com/upcoming-events)) and welcome additions to our [weekly agenda items](https://forum.ansible.com/t/documentation-working-group-agenda/153).
+
+## Branching for new stable versions
+
+The branching strategy for this repository mirrors the [`ansible/ansible`](https://github.com/ansible/ansible) repository.
+When a new `stable-*` branch is created in the core repository, a corresponding branch in the `ansible-documentation` repository needs to be created.
+There are various other changes that should occur around the same time that the new stable branch is cut.
+
+### Creating stable branches
+
+Create new stable branches as follows:
+
+```bash
+# Make sure your checkout is up to date.
+git fetch upstream
+
+# Create a new stable branch against the devel branch.
+git checkout -b stable-2.18 upstream/devel
+
+# Push the new stable branch to the repository.
+git push upstream stable-2.18
+```
+
+After the new stable branch is created, the following changes should be committed as pull requests to the new stable branch:
+
+* Update the core branch in the `docs/ansible-core-branch.txt` file.
+* Remove devel-only tooling.
+* Update Python versions in the support matrix.
+
+### Updating the core branch
+
+The script that grafts portions of the core repository uses the `docs/ansible-core-branch.txt` file to specify which branch to clone.
+When a new stable branch is created, modify the file so that it specifies the correct version.
+
+```bash
+sed -i 's/devel/stable-2.18/g' docs/ansible-core-branch.txt
+```
+
+### Removing devel-only tooling
+
+There are some scripts and other tooling artefacts that should be on the `devel` branch only.
+After creating a new stable branch, remove the appropriate files and references.
+
+```bash
+# Remove the following workflow files, the tagger script, and tagger requirements.
+git rm -r .github/workflows/pip-compile-dev.yml .github/workflows/pip-compile-docs.yml .github/workflows/reusable-pip-compile.yml .github/workflows/tag.yml hacking/tagger tests/tag.*
+```
+
+Next, remove references to the tagger dependencies as follows:
+
+1. Remove the reference from the typing input file.
+
+   ```bash
+   sed -i '/-r tag.in/d' tests/typing.in
+   ```
+
+2. Clean up the typing lockfile.
+
+   ```bash
+   nox -s pip-compile -- --no-upgrade
+   ```
+
+3. Open `noxfile.py` and remove `"hacking/tagger/tag.py",` from the `LINT_FILES` tuple.
+
+### Update Python versions in the support matrix
+
+The minimum supported Python version changes with each Ansible core version.
+This requires an update to the support matrix documentation after a new stable branch is created to reflect the appropriate Control Node Python versions.
+
+Uncomment the new stable version from the `ansible-core support matrix` section in the `docs/docsite/rst/reference_appendices/release_and_maintenance.rst` file.
+Submit a PR with the changes and request a core team review.
+
+### Updating the tagger script
+
+Update the list of active branches in the `hacking/tagger/tag.py` script on the `devel` branch.
+Add the new stable branch and remove the lowest version from the `DEFAULT_ACTIVE_BRANCHES` tuple.

README.md

@@ -114,7 +114,7 @@ The lock files contain tested dependencies that are automatically updated on a w
 
 If you'd like to use untested dependencies, set `PINNED=false` as in the following example:
 
-```
+```bash
 PINNED=false nox -s "checkers(docs-build)"
 ```
 
@@ -158,7 +158,7 @@ This will determine any missing `ansible-core` tags and create them in `ansible-
 nox -s tag
 
 # If you use a different upstream remote, specify the name.
-nox -s tag -- --remote <name> tag 
+nox -s tag -- --remote <name> tag
 
 # If your core repo is not in the same filesystem location, specify the path.
 nox -s tag -- --core <path> tag