ansible core documentation release checklist

Ansible-core release overview

Our work for an upcoming release starts when a new stable branch is created for the upcoming ansible-core release. Since we have to touch multiple releases, this means that:

• Most changes start in the devel branch and get backported to the new stable branch for the upcoming release.
• Some changes to support the version switcher have to be backported to all maintained releases.
• One set of changes has to happen in the newly EOL’d branch.

In general, when an ansible-core release happens, the prior release status changes. Core maintains 3 active releases, but with slightly different status. And the oldest maintained release usually goes EOL. (NOTE: the only except to this is ansible 2.9. Check with marketing when that goes EOL for Red Hat because we cannot fully EOL those docs until that date).

To make this clear in the instructions below, we’ll use the following conventions:

• devel - is the core-NEW+1 release. This happens as soon as the stable-NEW branch is created.
• stable-NEW - reflects the newly created stable branch for the upcoming release.
• stable-NEW-1 and stable-NEW-2 - reflects the two prior releases that will continue to be maintained.
• stable-EOL - the release before stable-NEW-2 that will go EOL once stable-NEW is released.

So for example, for ansible-core 2.14 release:

• devel is core-2.15.
• stable-NEW is stable-2.14(the newly created branch)
• stable-NEW-1 is stable-2.13, and stable-NEW-2 is stable-2.12
• stable-EOL is stable-2.11.

Checklist steps before release occurs

Create a tracking issue at https://github.com/ansible/ansible/issues similar to the core-2.14 checklist. The following steps go into more detail on the checklist items tracked in that issue. Each main step below should be its own PR if changes are required. Substep changes can be made in the same PR as the main step.

NOTE: Unless otherwise stated, do NOT MERGE any PRs until release day.

1. Review changelogs in stable-NEW in the changelogs/changelog.rst file. This is just a general scan to ensure it's a well-formed RST file. We do not edit changelogs as it requires finding the appropriate fragment and editing that instead of this generated file. This generated file may not appear until the first release candidate is created.
2. Review the core porting guide (at docs/docsite/rst/porting_guide/porting_guide_NEW.rst) as follows:
   1. Ensure it links to stable-NEW changelogs reviewed in the prior step.
   2. Ensure it is included at the top of docs/docsite/rst/porting_guides/core_porting_guides.rst file.
   3. Review for style/grammar. This is a light review for readability, etc.
   4. All changes are made to devel and backported to stable-NEW.
   5. Merge and backport to stable-NEW.
3. Update ansible-core changelogs table in release_and_maintenance.rst as follows:
   1. Change devel status column to ansible-core-NEW+1 release version.
   2. Add a row for stable-NEW with a status of Maintained (security and general bug fixes) and The proposed EOL date (check with core team on the date).
   3. Add a link for stable-NEW to its changelog. Follow the link pattern already set in the file.
   4. Change stable-NEW-1 status to Maintained (security and critical bug fixes)
   5. Change stable-NEW-2 status to Maintained (security bug fixes only)
   6. Change stable-EOL status to EOL. (this is effectively stable-NEW-3). Verify with core that the branch is going EOL.
4. Update core_conf.py as follows. See Understanding the Ansible conf.py files for background information: under html_context:
   1. Set 'latest_version': NEW (where NEW is the upcoming core release number)
   2. Set 'available_versions' to NEW, NEW-1, NEW-2, devel (filling in NEW as the upcoming core release number).
   3. Verify Ansible package porting guide and roadmaps are listed under ‘exclude_patterns’.
5. In stable-NEW only: In core_conf.py: change VERSION (capitalized) from devel to NEW. (where NEW is the upcoming core release number).
6. Create and test any redirects in the ansible/docsite repo.

Checklist steps on release day

1. Merge step 3, 4, and 5 PRs from above.
2. Backport step 3 above to stable-NEW.
3. Backport step 4 to stable-NEW, stable-NEW-1, stable-NEW-2.
4. Do NOT backport step 5. This change only happens in stable-NEW.
5. Publish devel, stable-NEW, stable-NEW-1, and stable-NEW-2`.
6. Merge and publish any redirects in ansible/docsite repo.

Checklist steps after release day

1. Update the backport instructions to target the stable-NEW branch See https://github.com/ansible/ansible/pull/77958.
2. In the Swiftype engine website:
3. Select *Ansible Core` engine. (Note this is a misnomer. It is actually indexing the Ansible package).
4. Select Manage > Domains from the left-hand navigation.
5. Select Manage Crawl Rules from the Manage dropdown on the right.
6. Under the excludes list, select Add rule.
7. Addstable-EOL to Begins With and select Add.
8. Return toe * Manage > Domains* and select reindex under the Manage dropdown.

Checklist to End-of-life the EOL docs

In the stable-EOL branch:

1. Update core_conf.py to set 'is_eol': True and merge.
2. Publish EOL Docs and verify EOL banner shows up at the top of the page and version switcher is no longer present on the left-hand navigation.

See also

• Ansible documentation release checklists
• Return to docs wiki