[Bug 255318] handbook: Document how to update the bootloader

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=255318

Graham Perrin <grahamperrin@gmail.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|grahamperrin@gmail.com      |doc@FreeBSD.org
           Severity|Affects Some People         |Affects Many People
           Assignee|doc@FreeBSD.org             |grahamperrin@gmail.com
           Keywords|                            |loader

--- Comment #15 from Graham Perrin <grahamperrin@gmail.com> ---
(In reply to Graham Perrin from comment #13)

Alternatives to the MarkMail URL: 

<https://www.mail-archive.com/freebsd-current@freebsd.org/msg186720.html>
<https://lists.freebsd.org/archives/freebsd-current/2022-August/002408.html>


(In reply to commit-hook from comment #10)

>>    …
>>    Currently, the section does not explain when or why bootcode has to be
>>    updated. It just references some related manual pages.
>>    …

That is, <https://docs.freebsd.org/en/books/handbook/book/#updating-bootcode>;
and (from base 9ecf6e0f9f25) the example in loader.efi(8) is good:
<https://man.freebsd.org/cgi/man.cgi?query=loader.efi&sektion=8&manpath=freebsd-release#EXAMPLES>
(thanks again, 0mp).

----

^Triage: with stable/12 end of life and 14.0-RELEASE both approaching, I
reckon: 

a)
<https://github.com/freebsd/freebsd-doc/blob/main/documentation/content/en/books/handbook/cutting-edge/_index.adoc#23-performing-minor-and-major-version-upgrades>
 should gain a warning, for readers to know that attention to an ESP might be
essential

* two warning boxes plus a note box might be overwhelming, as a trio, so this
  ESP-related warning must be concise

* refer to the 'Updating Bootcode' section of the chapter

b)
<https://github.com/freebsd/freebsd-doc/blob/main/documentation/content/en/books/handbook/cutting-edge/_index.adoc#3-updating-bootcode>
should be expanded, at least

* paraphrase the instruction to _stop_ using gpart(8) for ESP partitions

* refer directly to the EXAMPLES section of loader.efi(8)

* hint that if multiple ESPs exist, attention to more than one may be 
  appropriate (mirrored disks, for example).

<https://www.freebsd.org/releases/13.0R/relnotes/#boot>
<https://www.freebsd.org/releases/13.2R/relnotes/#boot>

! There is no stop note for 13.2, and upgrades from 12.⋯ to 13.2-RELEASE
  are expected (not all departures from 12.⋯ will go to 14.⋯), so 
  let's document this ASAP.

-- 
You are receiving this mail because:
You are the assignee for the bug.
You are on the CC list for the bug.