foreman-documentation Improve pre-upgrade documentation

What changes are you introducing?

This PR reviews the parts of the Upgrade guide that describe what happens before users start upgrading. I'm splitting this content into "Planning" and "Procedure prerequisites".

I'm proposing one new assembly:

"Preparing for Project upgrade": This groups all information relevant before users roll up their sleeves to start the actual upgrade process.

And then three different prerequisite-like sections:

"Planning Project upgrade": This is part of "Preparing for Project upgrade". This section lists general considerations + actions to be taken when preparing for the upgrade process as a whole.
"Prerequisites" in the procedure "Upgrading a ProjectServer": This part lists very specific actions to be taken right before following the server upgrade procedure.
"Prerequisites" in the procedure "Upgrading a SmartProxy": This part lists very specific actions to be taken right before following the proxy upgrade procedure.

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

Suboptimal upgrade experience. I shared a more detailed explanation and justification in https://issues.redhat.com/browse/SAT-29153

Before, the pre-upgrade information was included in various multiple sections throughout the guide and there was quite a lot of duplication. Reviewing the pre-upgrade information and grouping it into fewer sections will guide users through the pre-upgrade process more smoothly.

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

The diff shows a lot of deletions but the only ~~two~~ items I'm actually removing are ~~one obsolete prerequisite and another irrelevant prereqs~~ items that are obsolete now. ~~Both~~ All removals are highlighted in ~~a separate commit~~ separate commits for easier review. The rest of the removed lines is just me removing duplicate content (there was a lot of it).

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:

[ ] Foreman 3.14/Katello 4.16
[ ] Foreman 3.13/Katello 4.15 (EL9 only)
[ ] Foreman 3.12/Katello 4.14 (Satellite 6.16; orcharhino 7.2 on EL9 only)
[ ] Foreman 3.11/Katello 4.13 (orcharhino 6.11 on EL8 only; orcharhino 7.0 on EL8+EL9; orcharhino 7.1 with Leapp)
[ ] 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)
We do not accept PRs for Foreman older than 3.7.

May 14 '25 09:05 aneta-petrova

The PR preview for 5e0a9f8acb10d9c9e8a438b47c92ae4e8c00d635 is available at theforeman-foreman-documentation-preview-pr-3855.surge.sh

The following output files are affected by this PR:

show diff

show diff as HTML

May 14 '25 09:05 github-actions[bot]

I'm looking at @evgeni and @ehelms here, but also don't want to blow up the scope too much @aneta-petrova.

The scope for now is only "things users need to know/do before they upgrade".

I'd suggest to make the Katello and Satellite upgrade procedures the same.

I'll note your suggestion to align the actual upgrade procedures in the downstream ticket I have (https://issues.redhat.com/browse/SAT-34002). That will help me remember when I get to the actual upgrade part.

We should also make sure the Smart Proxy installation guide always tells users to sync content and install that way.

Just for the sake of accountability: I'm looking at upgrades now, not installation. So I don't expect to take any action based on this. (also to avoid blowing up the scope too much and all :))

May 15 '25 07:05 aneta-petrova

Just for the sake of accountability: I'm looking at upgrades now, not installation. So I don't expect to take any action based on this. (also to avoid blowing up the scope too much and all :))

But I think it is related. You will confuse users if we tell them that you upgrade by syncing content but never instructed them to set it up in the first place. If so, we need to think about a migration to get them into the newly preferred path. Or not do it at all.

May 15 '25 07:05 ekohl

But I think it is related. You will confuse users if we tell them that you upgrade by syncing content but never instructed them to set it up in the first place. If so, we need to think about a migration to get them into the newly preferred path. Or not do it at all.

I opened https://github.com/theforeman/foreman-documentation/pull/3856 to address this on the Proxy Installation guide's side.

May 19 '25 07:05 aneta-petrova

Hi @ekohl and @evgeni, do you have any further comments from the technical point of view? If not, do you feel like you can give this an ack?

Hi @bangelic, a similar question for you :) Do you have any further comments from the style point of view?

In the meantime, I also asked @maximiliankolb to take a look to make sure I don't break anything for orcharhino.

May 19 '25 08:05 aneta-petrova

I believe the last lingering issue around versioning has been resolved. Unless there is further feedback, I'll merge tomorrow.

May 20 '25 13:05 aneta-petrova

Merged to "master", no cherry-picks.

May 21 '25 07:05 aneta-petrova