MAINTAINERS.md
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.
Any modifications to the DCO or COPYING file must be reviewed and approved by the Red Hat open-source legal team.
Send an email with the request to [email protected] with [email protected] on copy.
At the start of each week the .github/workflows/pip-compile-* workflows run.
These workflows bump dependencies and create pull requests such as PR 2842.
PRs to bump dependencies should be merged in a timely fashion. The documentation repo categorizes dependencies into separate requirements files. The weekly schedule for workflow runs also ensures fewer dependencies are bumped at a time. This granularity and isolation helps us detect incompatibilities and issues that a new version of a dependency might introduce.
When reviewing PRs to refresh dependencies, look at the files changed and note the name of the requirements file.
This corresponds to a check in CI; for example tests/static.txt contains the dependencies for the nox / Run nox static session check.
In general, CI check will emit errors or warnings if the dependency refresh introduces an issue of some kind. So basically, during review, expand the CI checks and look for problems in the output of the relevant steps. If there are no errors, warnings or other messages and the step has run successfully, the dependency bump should be fine to approve and merge.
In most cases, when a dependency refresh causes an issue, you probably need to adjust something in the appropriate session in noxfile.py.
For example, PR 1172 bumped the version of ruff which resulted in a warning because the static session included a deprecated command.
To fix the issue, PR 1191 updated the ruff command and was merged before PR 1172.
When a new major Ansible version is released, you need to update the latest version in the scheduled docs build.
Open .github/workflows/build-latest-docs.yaml for editing.
Modify the repository-branch and ansible-package-version fields in the build-package-docs and deploy-package-docs jobs, for example:
# Values for the Ansible 11 release
with:
ansible-package-version: '11'
repository-branch: 'stable-2.18'
# Values for the Ansible 12 release
with:
ansible-package-version: '12'
repository-branch: 'stable-2.19'
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:
docs/ansible-core-branch.txt file.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-*.yml .github/workflows/reusable-pip-compile.yml .github/workflows/tag.yml .github/workflows/build-*-docs.yaml .github/workflows/reusable-*-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 the LINT_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.
The ansible-community/package-doc-builds repository holds the deployed output of package doc builds.
For each version of the Ansible package that is currently supported, there needs to be a corresponding branch in the ansible-community/package-doc-builds repository.
Before the docs for new package version can be built on Read the Docs, someone needs to create a branch as follows:
# Make sure your checkout is up to date.
git fetch upstream
# Create the new package version branch against the devel branch.
git checkout -b 11 upstream/devel
# Push the new package version branch to the repository.
git push upstream 11
The build workflow lists the Ansible package versions as input options, for example:
options:
- devel
- '11'
- '10'
- '9'
After creating a new branch for the Ansible package version in the ansible-community/package-doc-builds repository, you should check that the build workflow lists that version as an option.
If the version is not listed, open a PR against the devel branch to update the workflow file.
There are two Read the Docs projects associated with the ansible-documentation repository, as follows:
The Ansible package and Ansible core projects use separate configuration files, as follows:
package-doc-builds repository at https://github.com/ansible-community/package-doc-builds/blob/devel/.readthedocs.yamlansible-documentation repository at https://github.com/ansible/ansible-documentation/blob/devel/.readthedocs.yamlEach branch has its own Read the Docs configuration file.
Most of the time there is no need to update the Read the Docs configuration files. The only change that should be necessary between versions is the Python version, for example:
build:
os: ubuntu-lts-latest
tools:
python: >-
3.11
This Python version should match whatever version is used in the ansible-documentation repository to compile requirements and build the documentation.
For example, the stable-2.18 branch uses Python 3.11.
The Python version should be also be 3.11 in the Read the Docs configuration for both Ansible package and Ansible core.
You can verify the Python version in the pip-compile session of the noxfile.py on the respective branch.
In the Read the Docs settings, the Build pull requests for this project option is selected only for the Ansible core project. The configuration file for that project is in the
ansible-documentationrepository, which accepts pull requests. Thepackage-doc-buildsrepository is used to hold generated artifacts from the build workflow and does not get pull requests.
When there is a new version of the Ansible package or Ansible core, someone needs to updates the Read the Docs project.
To update the Ansible package project, do the following:
XX branch.To update the Ansible core project, do the following:
stable-* branch.Hiding older versions removes them from the fly-out menu on Read the Docs. Older versions of the documentation that are not supported or EOL should be hidden. It is also possible to hide doc builds before they are released to evaluate the content. At release day, all that is needed is to toggle the switch so the build is no longer hidden and, in the case of the package docs, update the default branch for the project.
To hide versions, do the following:
See How to hide a version and keep its documentation online for more information.
For the Ansible community package docs, it is necessary to add older versions to the robots.txt file to block crawlers.
This ensures that only the latest version is indexed by Google, for example.
Normally Read the Docs automatically adds versions to robots.txt when you hide those versions.
However because we use subprojects, this does not take effect.
There should only be one robots.txt file per domain, which you can find here:
To disallow a version when hiding or archiving it, do the following:
Content available at ansible.readthedocs.io/projects/ansible/ is built and deployed from the ansible-documentation repository using a GitHub workflow.
This section explains how maintainers can build and deploy the Ansible package docs using that workflow.
Details about what each job in the workflow does is beyond the scope of this maintainer guide. Refer to the comments in the workflow itself for more information.
The Ansible package docs build workflow allows you to run a Sphinx build with the make webdocs target on GitHub hosted runners.
The workflow can build from any account or org as well as from the ansible-documentation repository.
For instance, if you wanted to build the content of a branch in someone's fork, you can provide those details as inputs when running the workflow.
To build the docs, do the following:
If the workflow fails for any reason, the
docs-botposts a message in the#docs:ansible.comchannel on Matrix.
When the workflow run is complete, you can find the output available as an artifact on the Summary page. The artifact is named package-docs-build and contains a tarball with the generated HTML and other build assets.
To evaluate changes from a particular branch, you can deploy the docs build to a stage environment at https://ansible-community.github.io/package-doc-builds/.
This stage environment is a GitHub pages deployment.
When you deploy to stage, a job in the workflow run unpacks the contents of the package-docs-build artifacts and pushes them to the gh-pages branch of the ansible-community/package-doc-builds repository.
To deploy to stage, do the following:
Ansible package docs build workflow.If the build job succeeds, a member of the community-docs-maintainers team must review and approve the deployment.
You can find details about the workflow run, including a link to the stage deployment, from the Summary page of the workflow run. Build logs are available from each job in the workflow run.
To publish Ansible package docs to Read the Docs, do the following:
ansible-community/package-doc-builds repository.
For example, if you want to publish version 10 of the package docs then a branch named 10 should exist in the repository.
The deploy job pushes the generated HTML and other build assets to that target branch.Ansible package docs build workflow.If the build job succeeds, a member of the community-docs-maintainers team must review and approve the deployment.
You can find details about the workflow run, including a link to the Read the Docs project deployment, from the Summary page of the workflow run. Build logs are available from each job in the workflow run.
The resulting documentation is available on Read the Docs only if the version is active in the
package-doc-buildsproject. If the version is hidden in the project, that documentation will not be available in the fly-out menu or search results.
The deploy-package-docs job in the Ansible package docs build workflow uses a deployment protection rule.
This rule requires a member of the community-docs-maintainers team to review any deployment to stage or Read the Docs.
Members of that team can do the following when they receive email notifications of pending deployments:
You should always provide comments to justify deployment rejections.