git: bcd8df85f8 - main - handbook/cutting-edge: Add an introduction

The branch main has been updated by des:

URL: https://cgit.FreeBSD.org/doc/commit/?id=bcd8df85f82364e7879145edadcd67d46fba4cc9

commit bcd8df85f82364e7879145edadcd67d46fba4cc9
Author:     Dag-Erling Smørgrav <[email protected]>
AuthorDate: 2026-07-27 10:38:16 +0000
Commit:     Dag-Erling Smørgrav <[email protected]>
CommitDate: 2026-07-27 10:38:16 +0000

    handbook/cutting-edge: Add an introduction
    
    Add an introduction section which explains the terms “major version”,
    “minor version”, and “patch level”, explains the difference between
    updating and upgrading, and outlines what sort of upgrades we do and do
    not support.
    
    It is unfortunate that the FreeBSD support model is not documented in
    the Handbook or, indeed, anywhere except our mailing list archive.  As a
    compromise, this introducion links to the security page on the website,
    which briefly mentions the support model and links to the relevant
    emails in the archive.
    
    Reviewed by:    carlavilla, imp
    Differential Revision:  https://reviews.freebsd.org/D58471
---
 .../en/books/handbook/cutting-edge/_index.adoc     | 35 ++++++++++++++++------
 1 file changed, 26 insertions(+), 9 deletions(-)

diff --git a/documentation/content/en/books/handbook/cutting-edge/_index.adoc b/documentation/content/en/books/handbook/cutting-edge/_index.adoc
index 79f4094381..8c46c4a368 100644
--- a/documentation/content/en/books/handbook/cutting-edge/_index.adoc
+++ b/documentation/content/en/books/handbook/cutting-edge/_index.adoc
@@ -76,6 +76,31 @@ Throughout this chapter, `git` is used to obtain and update FreeBSD sources.
 Optionally, the package:devel/git[] port or package may be used.
 ====
 
+[[updating-introduction]]
+== Introduction
+
+=== Major and Minor Versions
+
+Since FreeBSD 6.0-RELEASE, FreeBSD releases have adhered strictly to a two-level numbering scheme.
+We use the term “major version” to describe the first part of the version number, e.g. the “14” in “14.3-RELEASE”, and the term “minor version” to describe the second part of the version number, e.g. the “3” in “14.3-RELEASE”.
+
+Additionally, FreeBSD release branches have a patch level, which is omitted when zero and incremented with every batch of security advisories and errata notices, e.g. “14.3-RELEASE-p7” for the seventh batch of patches published for FreeBSD 14.3.
+
+As a consequence of the https://www.FreeBSD.org/security/#model[FreeBSD support model], FreeBSD version numbers increase monotonically within the same major version, but not across different major versions.
+For instance, FreeBSD 14.2-RELEASE, 13.5-RELEASE, 14.3-RELEASE, 15.0-RELEASE, 14.4-RELEASE, and 15.1-RELEASE were released in that order.
+
+=== Updating vs. Upgrading
+
+We use the term “updating” to describe applying security or errata patches which may increment the patch level but do not increment the version number, and the term “upgrading” to describe replacing the entire base system with one with a different version number.
+
+=== Upgrade Paths
+
+Once installed, FreeBSD may be updated or upgraded using crossref:cutting-edge[updating-upgrading-freebsdupdate,binary patches], crossref:cutting-edge[pkgbase,packages], or crossref:cutting-edge[makeworld,from source].
+In all cases FreeBSD only supports updating or upgrading from a chronologically older version to a more recent one.
+
+Specifically, FreeBSD supports updating to a more recent patch level of the same version, or upgrading from a given version to either a more recent minor version of the same major version (e.g. from 14.3 to 14.4) or to a more recent version of the next major version (e.g. from 14.3 to 15.0 or 15.1).
+Moving to an older release of the same major version (e.g. from 14.4 to 14.3), to an older release of the next major version (e.g. from 14.4, released in March 2026, to 15.0, released three months earlier in December 2025), or skipping a major version (e.g. from 13.5 to 15.1) is neither recommended nor supported, even if the tools allow it.
+
 [[updating-upgrading-freebsdupdate]]
 == FreeBSD Update
 
@@ -246,15 +271,7 @@ This is particularly helpful when maintaining multiple systems, as it allows for
 [[freebsdupdate-upgrade]]
 === Performing Minor and Major Version Upgrades
 
-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 13.2 to 14.0.
-
-Both types of upgrade can be performed by providing `freebsd-update` with a release version target.
+Upgrading to a newer minor or major version can be performed by providing `freebsd-update` with a release version target.
 
 [WARNING]
 ====