From nobody Mon Jul 27 10:38:33 2026 X-Original-To: dev-commits-doc-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4h7w722yVBz6mmcR for ; Mon, 27 Jul 2026 10:38:38 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "YR1" (not verified)) by mx1.freebsd.org (Postfix) with ESMTPS id 4h7w722Krzz3QYG for ; Mon, 27 Jul 2026 10:38:38 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1785148718; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=kwZPdwYA4VrGD1InC024jwhCjRj3uj6cIG79nUiveBE=; b=sFu13uLxNjYXjYd3ODEshtM85WjpdTnkRm787XJP0Wqyh/rjmhd4mcAKydfeiJqdP3m4U3 GCXWc12wObCrYZ9S/QN92osvVX8NtBAnLKDzmSo4kyOqx9cmJKdjDVyiqCgti7WkswADHB YkcXXpiPbBz2EdUqFGZkkPBcqk9XNyKb86wWakMCxLtJMYyX2nm5p4ZwboRBoPkktG6X1r 28JpECOjGSe07APcZKo8SjtyZfXcVdHLKXUTJZB6dzADwf3YB/VCx08JnacVO93xddBO0D 9d7TSpDhKoF+JJCaH5Wn2VDhxh6lqeAIWZc0eJXbK5+X0nNy0wrcGgYHdKhH6Q== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1785148718; a=rsa-sha256; cv=none; b=dhkkRppDIFvBUSXiPdOfQcEVTcaH4zNXoMhJFJwnnzcYpnIYk93qG2Cj0MEW+Qb3st6YXs NO3xZdjaNhmcmTftgQg0zSyLqVIs9YC1+xgPWqt0/RvatTAaQSNTTIWCwrb4FSK9eyzqHS 1zKU6k6iSQAfJ3F8K/46R3T3VyPsiiRoeLsG4hm9101DOc5sx/zYQDLQ6PZ/sxCUSqrBnm nXZOaz8Sr/P+WOp8uG3VAXoUXZOsqKZnkjiajhMcQ4TmCZYEEv/iRUYAfptIx1orGhnKXX r3gw9ZoktGcqLIC7b73xzhqwbxYy7SwyCkBj2aqzEUWD20oA+dFvI99clu5onQ== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1785148718; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=kwZPdwYA4VrGD1InC024jwhCjRj3uj6cIG79nUiveBE=; b=nSwh4Jw1OFfDaBT2MitFQ5yJ7SWDOTD2vOZmi9aN7+eSTWDUBkX538JwDVM/Hs0EOBj51C CjcB1PBZM1NNlW1CnlZ4BmXZKsMDnYrGoUrICNecML5/Sgi4eLqyYDzFqryATs+YgxUxv6 bqNw1LXnhVtzxGB+26okdLpDPcCNUPu8y3PI+YnwuWz7jOJj2zeswoGKLAH4chOpsvh7i+ 5yr7qZVf1kNow4zD3GgfzjH734sAMtSzXFNlS0pBM0TLwg7sbYBHQ5LXCH6xVMEJttm6nx /y4BVS9LHdXxOL7B3AdrBCvZdR45/0DMg5QqB8b7C2sOOO9sbQDPiFe9Pgbq/w== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) by mxrelay.nyi.freebsd.org (Postfix) with ESMTP id 4h7w721M3vz150L for ; Mon, 27 Jul 2026 10:38:38 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from git (uid 1279) (envelope-from git@FreeBSD.org) id 2116a by gitrepo.freebsd.org (DragonFly Mail Agent v0.13+ on gitrepo.freebsd.org); Mon, 27 Jul 2026 10:38:33 +0000 To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org From: Dag-Erling=?utf-8?Q? Sm=C3=B8rg?=rav Subject: git: bcd8df85f8 - main - handbook/cutting-edge: Add an introduction List-Id: Commit messages for all branches of the doc repository List-Archive: https://lists.freebsd.org/archives/dev-commits-doc-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-doc-all@freebsd.org Sender: owner-dev-commits-doc-all@FreeBSD.org List-Id: List-Post: List-Help: List-Subscribe: List-Unsubscribe: List-Owner: Precedence: list MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: des X-Git-Repository: doc X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: bcd8df85f82364e7879145edadcd67d46fba4cc9 Auto-Submitted: auto-generated Date: Mon, 27 Jul 2026 10:38:33 +0000 Message-Id: <6a673529.2116a.7cbaa3ae@gitrepo.freebsd.org> The branch main has been updated by des: URL: https://cgit.FreeBSD.org/doc/commit/?id=bcd8df85f82364e7879145edadcd67d46fba4cc9 commit bcd8df85f82364e7879145edadcd67d46fba4cc9 Author: Dag-Erling Smørgrav AuthorDate: 2026-07-27 10:38:16 +0000 Commit: Dag-Erling Smørgrav 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] ====