Split Updating Guide

[mjivraja]

We need to split the updating guide from the Upgrading and Updating Guide. I have kept this limited to Downstream only at this level but definitely we can raise the scope to other builds. This may contain technical modifications, general modifications, and at a modular level so, please don't hesitate to provide even minor feedback.

Please NOTE that this PR only focuses on Updating Guide and not the Upgrading Guide. It will have another PR from @AkshayGadhaveRH. So, please be cautious if you are merging this PR first.

• I am familiar with the contributing guidelines.

Please cherry-pick my commits into:

• Foreman 3.7/Katello 4.9 (planned Satellite 6.14)
• Foreman 3.6/Katello 4.8
• Foreman 3.5/Katello 4.7 (Satellite 6.13)
• Foreman 3.4/Katello 4.6 (EL8 only)
• Foreman 3.3/Katello 4.5 on EL7 & EL8 (Satellite 6.12 on EL8 only; orcharhino 6.4 on EL8 only)
• Foreman 3.2/Katello 4.4 on EL7 & EL8
• Foreman 3.1/Katello 4.3 on EL7 & EL8 (Satellite 6.11 EL7/8; orcharhino 6.3 on EL7/8)
• For Foreman 3.0 or older, please create a separate PR.
• We do not accept PRs for Foreman 2.4 or older.

[github-actions]

The PR preview for 9c05232 could not be generated

[Lennonka]

Is it a good idea to add a new guide to older versions? I'd add it just to Satellite 6.14. I don't think it's a good idea to make larger restructuring mid-flight, it could confuse current users.

[mjivraja]

Is it a good idea to add a new guide to older versions? I'd add it just to Satellite 6.14. I don't think it's a good idea to make larger restructuring mid-flight, it could confuse current users.

Yes, I agree with this view. We can start even start with 6.13 considering the BZs of the same at present.

[Lennonka]

A couple more ideas.

[Lennonka]

A couple more things. We have a broken build due to a non-existing link. Rebase after #2262 is merged.

[Lennonka]

Please, rebase.

[Lennonka]

I've updated the cherry-pick list to cp only to 3.7.

[mjivraja]

We may require some work from the upstream repo side.

[Lennonka]

We may require some work from the upstream repo side.

@mjivraja What exactly?

[Lennonka]

They should update every release we put out :)

@ehelms In that case, the recommendation is in order, isn't it? :)

[Lennonka]

A couple more suggestions.
Also:

• I'm wondering if the backup should be the first step in procedures instead of a prerequisite.
• I'm missing a restore step at the end of each procedure.
• In examples, the values that are to be replaced by the user should be formatted as such, i.e. _replaceable value_.

[Lennonka]

Please, rename this file to snip_steps-needs-reboot.adoc.

We should give a hint in the name what kind of content the snip has (steps or prerequisite or other).

[ekohl]

We already have ./guides/doc-Upgrading_Project/topics/snip_needs_reboot.adoc. I would expect something that moves it from the topic to the common modules instead of duplicating it. I'd do that as a separate PR that we merge before this one.

[mjivraja]

Ack your view on this @ekohl

I have renamed it as of now and it is present at both places including common/modules. I was expecting the Upgrading Guide to be at common/modules but not sure if it is considered in upcoming PRs. This will bring snip_steps-needs-reboot.adoc to common/modules eventually.

[ekohl]

We already have ./guides/doc-Upgrading_Project/topics/snip_needs_reboot.adoc. I would expect something that moves it from the topic to the common modules instead of duplicating it. I'd do that as a separate PR that we merge before this one.

[mjivraja]

• I'm missing a restore step at the end of each procedure.

@Lennonka I discussed this with platform team and we can draft this procedure. Can we consider this for the next PR?

[Lennonka]

• I'm missing a restore step at the end of each procedure.

@Lennonka I discussed this with platform team and we can draft this procedure. Can we consider this for the next PR?

@mjivraja What are you talking about?
The procedure already exists in the Admin guide. Just mention a link to it the same way as with the backup step.

[mjivraja]

@mjivraja What are you talking about? The procedure already exists in the Admin guide. Just mention a link to it the same way as with the backup step.

This is an outdated one. I will stick to the original plan we discussed on Monday.

[Lennonka]

Details, details, details... :)

[Lennonka]

One last suggestion and we're good to merge!

[Lennonka]

Cherry-picked:

• e604b88..2cd7515 3.7 -> 3.7

[maximiliankolb]

I believe the guide is still missing in the navigation on docs.theforeman.org. This is how I've added "Configuring hosts using Salt": 1bf2a4f

cc @mjivraja

[mjivraja]

I believe the guide is still missing in the navigation on docs.theforeman.org. This is how I've added "Configuring hosts using Salt": 1bf2a4f

cc @mjivraja

Thank you @maximiliankolb for pointing out. Here we go #2374
I have also tried adding Upgrading_Project

CC: @AkshayGadhaveRH