Handbook - Chapter 26 - potentially misleading note

From: Tomasz Kramkowski <tomasz_at_kramkow.ski>
Date: Wed, 18 Oct 2023 14:18:49 UTC

I was reviewing Chapter 26 of the handbook today in preparation for an
upgrade and I was reading section 26.2.3 "Performing Minor and Major
Version Upgrades" and noticed what may be a mistake.

After running `freebsd-update -r 13.2-RELEASE upgrade` the documentation
mentions running `freebsd-update install` but does so in a "Note".

To me, the way this reads makes it seem like it's a side-note and not a
core part of the updating process. I mentioned it in the #freebsd IRC
channel and at least one other user agreed and suggested this part
should either not be a note or be changed to a "Warning".

When treating this paragraph as a side-note, the documentation makes it
seem like the step following `freebsd-update -r 13.2-RELEASE upgrade` is
a reboot followed by a `freebsd-update install` (which would not result
in a complete upgrade).

I'm happy to submit a patch addressing this if there is agreement that
it should be changed.

As an aside, it was also mentioned on IRC that this section should
probably also more explicitly mention/reference updates to the ZFS
version and how it may require bootloader updates. At the moment this is
only mentioned in the ZFS chapter, and bootloader updates are only
mentioned in passing in a different part of chapter 26. Although I don't
think I know enough about what specifically it should say to suggest an


Tomasz Kramkowski