Paths

Table of Contentst

15.1: Improve upgrade instructions
ClosedPublic
Actions

Authored by ziaee on Tue, Jun 16, 11:45 AM.

Details

Reviewers

Group Reviewers

releng
docs

Commits

R9:d9b67188b5ea: 15.1: Improve upgrade instructions

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.

Diff Detail

Repository

R9 FreeBSD doc repository

Lint

Lint Skipped

Unit

Tests Skipped

Build Status

Buildable 73908
Build 70791: arc lint + arc unit

Event Timeline

ivy created this revision.Tue, Jun 16, 11:45 AM

Herald added a subscriber: ziaee. · View Herald TranscriptTue, Jun 16, 11:45 AM

ivy requested review of this revision.Tue, Jun 16, 11:45 AM

Harbormaster completed remote builds in B73908: Diff 179864.Tue, Jun 16, 11:45 AM

ivy added a reviewer: docs.Tue, Jun 16, 11:46 AM

ziaee added subscribers: dch, cperciva, bapt.Tue, Jun 16, 2:18 PM

ziaee added inline comments.

website/content/en/releases/15.1R/installation.adoc
120	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	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	this is definitely an improvement

ivy added inline comments.Tue, Jun 16, 3:17 PM

website/content/en/releases/15.1R/installation.adoc
120	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	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 added inline comments.Tue, Jun 16, 4:22 PM

website/content/en/releases/15.1R/installation.adoc
120	(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.

lukas.engelhardt_gmx.de added a subscriber: lukas.engelhardt_gmx.de.Wed, Jun 17, 8:18 PM

ziaee added a subscriber: markj.Thu, Jun 18, 12:05 AM

ziaee added inline comments.

website/content/en/releases/15.1R/upgrading.adoc
124	(suggested by @markj at hackathon)

ziaee added inline comments.Thu, Jun 18, 12:14 AM

website/content/en/releases/15.1R/upgrading.adoc
222	pointed out by @markj

@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
124	Yes please.

ivy retitled this revision from 15.1: Improve pkgbase upgrade instructions to 15.1: Improve upgrade instructions.Thu, Jun 18, 2:53 PM

Harbormaster completed remote builds in B73976: Diff 179997.Thu, Jun 18, 2:54 PM

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 requested changes to this revision.Thu, Jun 18, 3:21 PM

ziaee added inline comments.

website/content/en/releases/15.1R/installation.adoc
58	please revert the addition of this section, freebsd-update does this for you
132–133	please do not use term update to have clean separation between update and upgrade.
134	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
58	please revert addition of this section, freebsd-update does this for you
132–133	please use term upgrading for separation between update and upgrade
134	please revert changes to this line

This revision now requires changes to proceed.Thu, Jun 18, 3:21 PM

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.

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

website/content/en/releases/15.1R/installation.adoc
88–89	perhaps we can make this clearer, iiuc this is only for major version upgrades?

ziaee attached a referenced file: F160379068: ping-g440.jpg. (Show Details)Tue, Jun 23, 10:03 PM

ziaee mentioned this in D57789: 15.1: Indicate that machdep.bootmethod is x86-only.

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