git: a836774703 - main - [Handbook]: Clarify kernel modules on upgrades

From: Fernando Apesteguía <>
Date: Fri, 14 Apr 2023 12:43:40 UTC
The branch main has been updated by fernape:


commit a836774703facd9ab8b7bfd64ab1c6116631cdeb
Author:     Graham Perrin <>
AuthorDate: 2023-04-14 12:32:02 +0000
Commit:     Fernando Apesteguía <>
CommitDate: 2023-04-14 12:38:59 +0000

    [Handbook]: Clarify kernel modules on upgrades
    Forewarn users that FreeBSD-provided packages of kernel modules might be
    unusable with a new version of the OS until some time after the version is
    Approved by:            doceng@ (carlavilla@, fernape@)
    Reviewed By:            ceri@, jrm@
    Differential Revision:
 .../en/books/handbook/cutting-edge/_index.adoc     | 34 ++++++++++++++++++----
 1 file changed, 29 insertions(+), 5 deletions(-)

diff --git a/documentation/content/en/books/handbook/cutting-edge/_index.adoc b/documentation/content/en/books/handbook/cutting-edge/_index.adoc
index 28f00ad6e4..96d58bbb28 100644
--- a/documentation/content/en/books/handbook/cutting-edge/_index.adoc
+++ b/documentation/content/en/books/handbook/cutting-edge/_index.adoc
@@ -245,11 +245,35 @@ Rebuilding a custom kernel, even if nothing else changed, allows `uname` to accu
 This is particularly helpful when maintaining multiple systems, as it allows for a quick assessment of the updates installed in each one.
-=== Performing Major and Minor Version Upgrades
+=== Performing Minor and Major Version Upgrades
-Upgrades from one minor version of FreeBSD to another, like from FreeBSD 9.0 to FreeBSD 9.1, are called _minor version_ upgrades.
-_Major version_ upgrades occur when FreeBSD is upgraded from one major version to another, like from FreeBSD 9.X to FreeBSD 10.X.
-Both types of upgrades can be performed by providing `freebsd-update` with a release version target.
+Upgrades from one minor version of FreeBSD to another are called _minor version_ upgrades. An example: 
+- FreeBSD 13.1 to 13.2.
+_Major version_ upgrades increase the major version number. An example:
+- FreeBSD 12.4 to 13.2.
+Both types of upgrade can be performed by providing `freebsd-update` with a release version target.
+After each new `RELEASE`, FreeBSD package build servers will, for a limited period, *not* use the newer version of the operating system.
+This provides continuity for the many users who do not upgrade immediately after a release announcement.
+For example:
+* packages for users of 13.1 and 13.2 will be built on a server running 13.1, until 13.1 reaches end of life
+-- and, critically:
+* a kernel module that is built on 13.1 might *not* be suitable for 13.2.
+So, with any minor or major OS upgrade, if your package requirements include any kernel module:
+* *be prepared to build the module from source*.
@@ -606,7 +630,7 @@ In order to track changes for the whole source tree, subscribe to {dev-commits-s
 . To install a new FreeBSD-STABLE system, install the most recent FreeBSD-STABLE release from the crossref:mirrors[mirrors,FreeBSD mirror sites] or use a monthly snapshot built from FreeBSD-STABLE. Refer to link:[] for more information about snapshots.
 To compile or upgrade an existing FreeBSD system to FreeBSD-STABLE, use `git` to check out the source for the desired branch.
-Branch names, such as `stable/9`, are listed at link:[].
+Branch names, such as `stable/13`, are listed at link:[].
 . Before compiling or upgrading to FreeBSD-STABLE , read [.filename]#/usr/src/Makefile# carefully and follow the instructions in <<makeworld>>. Read the {freebsd-stable} and [.filename]#/usr/src/UPDATING# to keep up-to-date on other bootstrapping procedures that sometimes become necessary on the road to the next release.