Documentation Checklist: Ansible 13 release

[samccann]

Release checklist for Ansible 13 documentation. See follow on comment for full list.

[samccann]

Update the documentation and publish the 9 version of Ansible documentation. Tasks include:

Pre-release tasks:

• Stage the release docs on test when beta is available.
• Update the Release Status grid on the Release and Maintenance page in devel to link in changelogs. DO NOT mark Ansible 11 as EOL as it may be an 'LTS' release, and add Ansible 14 as in development.
• backport to stable-2.20 and stable-2.18 (if Ansible 11 will continue - TBD)
• Verify that the Ansible 13 porting guide has a link to the Ansible 13 changelog file in GitHub.
• Build docs and validate new collections docs after they are added to https://github.com/ansible-community/ansible-build-data
• Verify that release/main page and porting pages are kept in sync between latest and devel
• update conf.py:
  • Set 'latest_version', under html_context as follows:
    '13' if tags.has('ansible')
  • Update version switcher to remove Ansible 11 (TBD - need steering committee deicsion)
  • Verify core porting guide and roadmaps are listed under ‘exclude_patterns’.
  • Merge to devel on release day only
  • Backport to stable-2.20 , stable-2.18 (TBD if Ansible 11 remains).

In stable-2.20 branch:

• update conf.py VERSION to '13' if tags.has('ansible') or tags.has('all') else'

Update the build and docsite :

• Publish 13 on release day.
• Update the 2.9 to 13 redirects on the docsite repo by renaming the ansible/12 directory to ansible/13 and republish the docsite (no longer needed)

RTD changes:

• Navigate to Settings and update default branch to 13 at https://app.readthedocs.org/projects/package-doc-builds/
• Click the ... menu next to Version 13 and click Configure Versions . Update settings for the 13 build to unhide it.

Docs build workflow changes:

• Go to build-latest-docs.yml and update to core 2.20 and Ansible 13 in both places.

Post release:

• update intersphinx links. see add support for Ansible 9 intersphinx links #878
  • backport to stable-2.20 and republish

[samccann]

@oraNod pls review the checklist for what may or may not be needed now that we are on RTD. Some specific questions:

• Does RTD depend on the conf.py changes for latest?
• Does the version switcher even work on RTD? I seem to recall seeing a message that it doesn't really work so maybe we stop making updates until we can remove it?

@felixfontein @gotmax23 - Do we plan on keeping Ansible 11 around longer or does that EOL with Ansible 13 and we go back to having only devel and latest releases?

[felixfontein]

@samccann there will likely be a last Ansible 11 release after 13.0.0 comes out (together with a last Ansible 12 release) - only then they are both EOL. So they're still 'active' for the next two weeks.

[oraNod]

@samccann

This step is no longer needed:

Update the 2.9 <--> 13 redirects on the docsite repo by renaming the ansible/12 directory to ansible/13 and republish the docsite. (TBD - Need to see if this is still needed)

[oraNod]

For the RTD steps, here is what you need to do:

1. Go to https://app.readthedocs.org/projects/package-doc-builds/
2. Select + Add Version
3. Select 13.
4. Check the slug matches the version number, select Active, then Update Version.

Then go to the settings page: https://app.readthedocs.org/dashboard/package-doc-builds/edit/

Set the default branch to 13 and then save the changes.

To remove an older version from the RTD flyout widget, find the version in the project and then select the Hidden slider.

[oraNod]

When older versions are hidden you'll see it on the RTD dashboard like this:

[oraNod]

@samccann The changes to conf.py look fine to me too btw. I don't think that really has an impact on the RTD builds, more the version switcher. We still need to investigate that some more.

[oraNod]

Also when we hide a version, I'd propose that we also add that version to the disallow list in robots.txt a la ansible-community/ansible-docsite#496