Re: Handbook - Chapter 26 - potentially misleading note

On Wed, 18 Oct 2023 at 16:18, Tomasz Kramkowski <tomasz@kramkow.ski> wrote:
>
> Hi,
>
> 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
> amendment.
>
> Thanks,
>
> --
> Tomasz Kramkowski
>

Hi,

Yes, you can send a patch.

We're working on the 4th version of the handbook, in the near future
we'll upgrade this chapter.

Thanks for the report.