ansible core documentation release checklist - ansible/community GitHub Wiki
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 thecore-NEW+1
release. This happens as soon as thestable-NEW
branch is created.stable-NEW
- reflects the newly created stable branch for the upcoming release.stable-NEW-1
andstable-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
isstable-2.14
(the newly created branch)stable-NEW-1
isstable-2.13
, andstable-NEW-2
isstable-2.12
stable-EOL
isstable-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.
- Review changelogs in
stable-NEW
in thechangelogs/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. - Review the core porting guide (at docs/docsite/rst/porting_guide/porting_guide_
NEW
.rst) as follows:- Ensure it links to
stable-NEW
changelogs reviewed in the prior step. - Ensure it is included at the top of docs/docsite/rst/porting_guides/core_porting_guides.rst file.
- Review for style/grammar. This is a light review for readability, etc.
- All changes are made to
devel
and backported tostable-NEW
. - Merge and backport to
stable-NEW
.
- Ensure it links to
- Update
ansible-core
changelogs table in release_and_maintenance.rst as follows:- Change
devel
status column toansible-core-NEW+1
release version. - Add a row for
stable-NEW
with a status ofMaintained (security and general bug fixes)
and The proposed EOL date (check with core team on the date). - Add a link for
stable-NEW
to its changelog. Follow the link pattern already set in the file. - Change
stable-NEW-1
status toMaintained (security and critical bug fixes)
- Change
stable-NEW-2
status toMaintained (security bug fixes only)
- Change
stable-EOL
status to EOL. (this is effectivelystable-NEW-3
). Verify with core that the branch is going EOL.
- Change
- Update
core_conf.py
as follows. See Understanding the Ansible conf.py files for background information: under html_context:- Set 'latest_version': NEW (where NEW is the upcoming core release number)
- Set 'available_versions' to NEW, NEW-1, NEW-2, devel (filling in NEW as the upcoming core release number).
- Verify Ansible package porting guide and roadmaps are listed under ‘exclude_patterns’.
- In stable-NEW only: In core_conf.py: change VERSION (capitalized) from
devel
toNEW
. (where NEW is the upcoming core release number). - Create and test any redirects in the ansible/docsite repo.
Checklist steps on release day
- Merge step 3, 4, and 5 PRs from above.
- Backport step 3 above to
stable-NEW
. - Backport step 4 to
stable-NEW,
stable-NEW-1, stable-NEW-2. - Do NOT backport step 5. This change only happens in
stable-NEW
. - Publish
devel
,stable-NEW
,stable-NEW-1
, and stable-NEW-2`. - Merge and publish any redirects in ansible/docsite repo.
Checklist steps after release day
- Update the backport instructions to target the
stable-NEW
branch See https://github.com/ansible/ansible/pull/77958. - In the Swiftype engine website:
- Select *Ansible Core` engine. (Note this is a misnomer. It is actually indexing the Ansible package).
- Select Manage > Domains from the left-hand navigation.
- Select Manage Crawl Rules from the Manage dropdown on the right.
- Under the excludes list, select Add rule.
- Add
stable-EOL
to Begins With and select Add. - Return toe * Manage > Domains* and select reindex under the Manage dropdown.
Checklist to End-of-life the EOL docs
In the stable-EOL
branch:
- Update core_conf.py to set 'is_eol': True and merge.
- 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.