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.

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. This does not need to wait for release day.
3. Update `ansible-core changelogs table in release_and_maintenance.rst as follows (do not merge until release day):
   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.
   7. DO NOT MERGE THIS PR. Set status to WIP and merge only on release day.
   8. Backport to stable-NEW and merge/publish on release day.
4. Update core_conf.py as follows (do not merge until release day):

See also

• Ansible documentation release checklists
• Return to docs wiki