From 3590f6550dda80110990d6635cdb0db35fbda931 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Thu, 10 Oct 2024 19:01:54 +0100 Subject: [PATCH] Documenting the branching process (#1956) * resolves #1772 documenting the branching process * Update README.md Co-authored-by: Maxwell G * Update README.md Co-authored-by: Felix Fontein * updates and suggestions * update the support matrix section * Update README.md Co-authored-by: Maxwell G * Update README.md Co-authored-by: Maxwell G * updates and suggestions * maintainers guide * rm active branch example * Update MAINTAINERS.md Co-authored-by: Sandra McCann --------- Co-authored-by: Maxwell G Co-authored-by: Felix Fontein Co-authored-by: Sandra McCann --- MAINTAINERS.md | 81 ++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 4 +-- 2 files changed, 83 insertions(+), 2 deletions(-) create mode 100644 MAINTAINERS.md diff --git a/MAINTAINERS.md b/MAINTAINERS.md new file mode 100644 index 0000000000..a662740efd --- /dev/null +++ b/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. diff --git a/README.md b/README.md index 2712aabf09..3bb09ee9c0 100644 --- a/README.md +++ b/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 tag +nox -s tag -- --remote tag # If your core repo is not in the same filesystem location, specify the path. nox -s tag -- --core tag