Rather than having multiple "special issues" pages, it would be helpful to have a specific upgrade doc for each version upgrade

[Garrett Neugent]

When an operator is planning out an OpenStack upgrade, currently they have to seek out and read through multiple pages to ensure that they don't find any hidden gotchas during an upgrade process. It would be nice instead if a given OpenStack upgrade (e.g Stein to Train) had a dedicated page instead of separate places to check (e.g. [0,1,2,3] to name a few), with all the steps to perform the upgrade safely.

[0] https://docs.openstack.org/project-deploy-guide/charm-deployment-guide/latest/placement-charm-upgrade-to-train.html
[1] https://docs.openstack.org/project-deploy-guide/charm-deployment-guide/latest/upgrade-issues.html#neutron-lbaas-upgrading-from-stein-to-train
[2] https://docs.openstack.org/project-deploy-guide/charm-deployment-guide/latest/upgrade-issues.html#designate-upgrading-from-stein-to-train
[3] https://docs.openstack.org/charm-guide/latest/release-notes/index.html

Thanks for your time!

[Peter Matulis (petermatulis)]

Garrett, thanks for your interest in making OpenStack Charms documentation better.

The thing is that your suggestion will just add to the number of pages that need to be read since there can be OpenStack upgrade issues [0,1] that are not related to a specific A-to-B upgrade.

[0] https://docs.openstack.org/project-deploy-guide/charm-deployment-guide/latest/upgrade-issues.html#octavia

[1] https://docs.openstack.org/project-deploy-guide/charm-deployment-guide/latest/upgrade-issues.html#ceph-option-require-osd-release

[Andrea Ieri (aieri)]

Hi Peter, what Garrett is essentially proposing is to move the responsibility of figuring out the full set of upgrade steps from the operator to the documentation maintainer.

In the current model we have generic pages and lists of gotchas; whoever needs to perform an upgrade has to determine which set of upgrade issues are relevant for their specific situation, and understand how those special instructions fit into the default process. This is of course error prone, and has to be repeated for every upgrade, by every operator.

The proposal is to instead have one page per upgrade (e.g. Stein-to-Train / Train-to-Ussuri / Ussuri-to-Victoria / etc), with all non-standard instructions already in the right place.

[Peter Matulis (petermatulis)]

https://review.opendev.org/c/openstack/charm-deployment-guide/+/843184

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.opendev.org/c/openstack/charm-deployment-guide/+/843184
Committed: https://opendev.org/openstack/charm-deployment-guide/commit/278f3d826bfda8f6cb5298e65cb9970ad7c68994
Submitter: "Zuul (22348)"
Branch: master

commit 278f3d826bfda8f6cb5298e65cb9970ad7c68994
Author: Peter Matulis <email address hidden>
Date: Tue May 24 15:14:59 2022 -0400

    Add dedicated OpenStack upgrade path pages

    Add dedicated OpenStack upgrade migration path pages to
    make it clearer for upgraders. Doing so also removes
    non-relevant text from the general upgrade-issues page.

    Add a redirect to account for the deleted placement
    charm special procedure page.

    Closes-Bug: #1970272
    Change-Id: Ibd09e9e0d66a6f9e152f37c6ac675eed35c97bde