Document high-level steps for upgrading

asteflova commented 3 weeks ago

What changes are you introducing?

Adding a high-level summary of the upgrade process loosely based on Upgrade paths in version 3.3. ("Loosely" because rather than re-create the original list of steps, I rather propose to add a very general summary in its place and include the other, more detailed steps as part of the assembly that actually describes upgrading.)
Removing the introduction for the upgrade assembly (guides/common/modules/con_upgrading-project.adoc) because it's out-of-date.
Enhancing the upgrade procedures with a few bits of information based on the old Upgrade paths section and the removed assembly introduction, to make sure we still keep the important parts.

Why are you introducing these changes? (Explanation, links to references, issues, etc.)

https://issues.redhat.com/browse/SAT-29113 points out that the high-level upgrade steps are missing in the latest version and requests adding it.

Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)

~~If I get an ack for this, I'd like to open another PR for 3.11 and below, but without the part about upgrading to EL 9.~~

Checklists

[x] I am okay with my commits getting squashed when you merge this PR.
[x] I am familiar with the contributing guidelines.

Please cherry-pick my commits into:

[x] Foreman 3.12/Katello 4.14 (Satellite 6.16)
[ ] Foreman 3.11/Katello 4.13
[ ] Foreman 3.10/Katello 4.12
[ ] Foreman 3.9/Katello 4.11 (Satellite 6.15; orcharhino 6.8/6.9/6.10)
[ ] Foreman 3.8/Katello 4.10
[ ] Foreman 3.7/Katello 4.9 (Satellite 6.14)
[ ] Foreman 3.6/Katello 4.8
[ ] Foreman 3.5/Katello 4.7 (Satellite 6.13; orcharhino 6.6/6.7)
We do not accept PRs for Foreman older than 3.5.

github-actions[bot] commented 3 weeks ago

The PR preview for cb1dd2b2c97d4ce583155cef55dd2494a868a873 is available at theforeman-foreman-documentation-preview-pr-3408.surge.sh

The following output files are affected by this PR:

show diff

show diff as HTML

asteflova commented 3 weeks ago

I reworked the Upgrade paths section to give an overview of the upgrade process, outlining that the upgrade can be executed in multiple phases. I'll appreciate honest feedback about whether I'm making things better or worse.

asteflova commented 3 weeks ago

I'd welcome @apinnick's thoughts on it as well. It's very tempting to continue restructuring, but we need to draw the line somewhere.

For example, I'd say section 1.2 Prerequisites still feels odd. While I certainly think that we should mention reading the release notes is needed, the disk space prerequisites probably belong in the specific upgrade sections. Also, the "plan for updating any scripts" is less of a prerequisite and more of a planning step.

I agree that there are opportunities for additional improvements but I am trying very hard to ignore them. I need to limit this PR to describing the high-level overview of the upgrade process (EDIT: to address the gap observed in https://issues.redhat.com/browse/SAT-29113) and also get it done in a timely manner.

asteflova commented 3 weeks ago

I requested @apinnick's review as suggested above. Avital, as you review the PR, can you please think about which changes need to be addressed for this PR to be good enough to merge and which changes could perhaps be postponed for later? Perhaps it might be a good idea to create an epic similar to the one you created for the installation guide.

ekohl commented 3 weeks ago

That's precisely my thinking. You can probably spend months on improving this document, but it's good to deliver some smaller improvements in time for 6.16.

apinnick commented 3 weeks ago

I requested @apinnick's review as suggested above. Avital, as you review the PR, can you please think about which changes need to be addressed for this PR to be good enough to merge and which changes could perhaps be postponed for later? Perhaps it might be a good idea to create an epic similar to the one you created for the installation guide.

@asteflova Done! I also linked an older epic for improving the disconnected upgrade guide (SAT-24751)

Upgrade guide improvements epic (SAT-29153)
Prerequisites/considerations improvements story (SAT-29154)

asteflova commented 3 weeks ago

@ekohl and/or @evgeni, do you have any further comments?

evgeni commented 3 weeks ago

I think that's a good improvement!

ekohl commented 3 weeks ago

Like others I think this is a good step forward and appreciate that we've also identified future work

asteflova commented 3 weeks ago

Merged to "master" and cherry-picked:

8536dca72c..639de86b30 3.12 -> 3.12

theforeman / foreman-documentation