15.1: Improve upgrade instructions

[ziaee]

Summary

• Do not say that these instructions can be used to upgrade from 14.4-RELEASE. Upgrading 14.x pkgbase to 15 is not supported and requires more steps to do properly

• Do not tell users they need to upgrade pkg(8) to upgrade the base system. This is not required.

• Clarify that ports kmods only need to be upgraded if ports are enabled.

[ziaee]

website/content/en/releases/15.1R/installation.adoc

120 ↗

(On Diff #179864)

my issue with this is that we have always supported upgrading from releasePrevLegacy, right? they cant upgrade from 14.4 to 15.0, right? that's downgrading things which have been mfc'ed.

133 ↗

(On Diff #179864)

iiuc per the discussion we had on irc, the consensus of @bapt, @dch, @cperciva, and I is that we do want to tell them this.

147 ↗

(On Diff #179864)

this is definitely an improvement

[ivy]

website/content/en/releases/15.1R/installation.adoc

120 ↗

(On Diff #179864)

we do support upgrading from 14.4 to 15.0, just not with pkgbase, because pkgbase wasn't supported in 14.4. that means it's missing all the changes we made for 15.0 to make seamless pkgbase upgrades work, and therefore the upgrade is much more complicated to do correctly. (this was an issue with all releases prior to 15.0, it just didn't come up because we didn't document pkgbase upgrades at all.)

note that you couldn't install 14.4 (or earlier) with pkgbase either, at least not via bsdinstall. this only affects users who manually switched their 14.x systems to pkgbase, and who were hopefully aware that pkgbase was not supported in 14.

i'm not opposed to documenting a way to upgrade from 14 to 15 with pkgbase, if someone wanted to write that (i can provide a broad outline of the steps required). the issue is that the current documented procedure (the one in this page) does not work and will lead to a broken / inconsistent base system, so we need to start by not telling people to do this.

133 ↗

(On Diff #179864)

i think we agreed to tell users to update their systems before upgrading, which is fine; i can add text for that if we want to continue doing that. that would basically be "run pkg upgrade before upgrading", or maybe "run pkg upgrade -r FreeBSD-base before upgrading".

what we can't/shouldn't do is tell users they need to install packages from ports to upgrade the base system -- this isn't required, and musn't ever be required.

[ziaee]

website/content/en/releases/15.1R/installation.adoc

120 ↗

(On Diff #179864)

(i can provide a broad outline of the steps required)

yes please. i can work that in quick which i think would address both of our concerns.

[ziaee]

website/content/en/releases/15.1R/upgrading.adoc

125

(suggested by @markj at hackathon)

[ziaee]

website/content/en/releases/15.1R/upgrading.adoc

231

pointed out by @markj

[cperciva]

@ivy Can you add the tweaks from ziaee/markj and commit this? I don't think we need to add the "how to upgrade from 14.4 pkgbase" instructions; that's an unsupported path and would bloat the document too much (and risk confusing users).

website/content/en/releases/15.1R/upgrading.adoc

125

Yes please.

[ivy]

rf

[ivy]

i've added mark's ZFS change and also documented this for the dist set path, as it's not pkgbase specific. i've added a new step for pkgbase to update the installed system, since we want users to be in the habit of doing this.

i haven't incorporated mark's other suggestion because i don't understand it:

+ Note that some installations may reversed case or not have freebsd/loader.efi.

what is "reversed case"?

[ziaee]

website/content/en/releases/15.1R/installation.adoc

58 ↗

(On Diff #179997)

please revert the addition of this section, freebsd-update does this for you

144 ↗

(On Diff #179997)

please do not use term update to have clean separation between update and upgrade.

148 ↗

(On Diff #179997)

please revert changes to this line. verbatim attributes is not for this, it is so you can use macros inside literal block.

website/content/en/releases/15.1R/upgrading.adoc

59

please revert addition of this section, freebsd-update does this for you

134–136

please use term upgrading for separation between update and upgrade

140

please revert changes to this line

[ziaee]

In D57606#1321620, @ivy wrote:

i've added mark's ZFS change and also documented this for the dist set path, as it's not pkgbase specific. i've added a new step for pkgbase to update the installed system, since we want users to be in the habit of doing this.

i haven't incorporated mark's other suggestion because i don't understand it:

+ Note that some installations may reversed case or not have freebsd/loader.efi.

what is "reversed case"?

sometimes it's EFI/FREEBSD/LOADER.EFI and sometimes it's efi/freebsd/loader.efi and we dont know really why. of course its related to the underlying efi fs does not have a notion of case.

[ziaee]

Ping, the release has shipped so any changes to these instructions should be made ASAP.

website/content/en/releases/15.1R/installation.adoc

99–100 ↗

(On Diff #179997)

perhaps we can make this clearer, iiuc this is only for major version upgrades?

[ziaee]

[ziaee]

Updating this in two identical files is bad. Asciidoctor has native redirects, I have proposed using these here, mostly just to brief our team that it's this easy: https://reviews.freebsd.org/D57792

[ivy]

sorry, i am unexpectedly busy irl. as you are more familiar with the docs style than me, it's probably easier for you to land this.

[ziaee]

No problem, I'm happy to help.

[vladlen]

website/content/en/releases/15.1R/installation.adoc

120 ↗

(On Diff #179864)

i'm not opposed to documenting a way to upgrade from 14 to 15 with pkgbase, if someone wanted to write that (i can provide a broad outline of the steps required). the issue is that the current documented procedure (the one in this page) does not work and will lead to a broken / inconsistent base system, so we need to start by not telling people to do this.

I'd like to take on documenting the 14.4 to 15.0 pkgbase upgrade path. Could you share the broad outline of steps you mentioned? I'll write up a draft and we can iterate from there.

My plan is to add this to the same upgrading.adoc, so it covers not only 15.0 → 15.1 upgrades but also the legacy 14.4 → 15.0 path. This would give users a complete upgrade story and additional motivation to move to the latest version.