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.
We have weekly meetings on Matrix every Tuesday.
See the Ansible calendar for meeting details.
The branching strategy for this repository mirrors the 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.
Create new stable branches as follows:
# 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.
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.
sed -i 's/devel/stable-2.18/g' docs/ansible-core-branch.txt
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.
# 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 .github/workflows/build-package-docs.yaml hacking/tagger tests/tag.*
Next, remove references to the tagger dependencies as follows:
-
Remove the reference from the typing input file.
sed -i '/-r tag.in/d' tests/typing.in
-
Clean up the typing lockfile.
nox -s pip-compile -- --no-upgrade
-
Open
noxfile.py
and remove"hacking/tagger/tag.py",
from theLINT_FILES
tuple.
Update the .github/workflows/pip-compile-dev.yml
workflow so that it includes the new stable branch and drops the oldest branch.
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.
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.