Skip to content

Commit

Permalink
[Handbook]: Clarify kernel modules on upgrades
Browse files Browse the repository at this point in the history
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
announced.

Approved by:		doceng@ (carlavilla@, fernape@)
Reviewed By: 		ceri@, jrm@
Differential Revision:	https://reviews.freebsd.org/D39474
  • Loading branch information
grahamperrin authored and fernape committed Apr 14, 2023
1 parent 8a74547 commit a836774
Showing 1 changed file with 29 additions and 5 deletions.
34 changes: 29 additions & 5 deletions documentation/content/en/books/handbook/cutting-edge/_index.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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.

[[freebsdupdate-upgrade]]
=== 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.

[WARNING]
====
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*.
====

[NOTE]
====
Expand Down Expand Up @@ -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:https://www.FreeBSD.org/snapshots/[www.freebsd.org/snapshots] 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:https://www.FreeBSD.org/releng/[www.freebsd.org/releng].
Branch names, such as `stable/13`, are listed at link:https://www.FreeBSD.org/releng/[www.freebsd.org/releng].
. 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.

[[translate-n-number]]
Expand Down

0 comments on commit a836774

Please sign in to comment.