From nobody Fri Apr 14 12:43:40 2023 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 4Pybj85dYDz459sd for ; Fri, 14 Apr 2023 12:43:40 +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 "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4Pybj854M9z3KwF; Fri, 14 Apr 2023 12:43:40 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1681476220; 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=JvCjLWfvXF5JPUsHNTTwfsig/8ie0Kb8ZBOZ90qlBnI=; b=UAhSrSntVJQCYipPRmtHGrEVei7Ta7vWYWsCzYW9gpXPdP5nO8lLXded0WSRnbJssufwXy XiAIZLXRT+D9ufjxRn1IRGNtITi1hlZoOpqs05jm/GJyRigvepEICPzQqQZpK1aFFKJ2q2 LUDcpPO59/qpARV9sM8wOrWVzoXGr+ZSa5tpa1HsTe1ROopDVDj15r+OzCk61GJ5zhIVMp EnNeCFavLUOg8wczOod2bDvcSyxUikt7v76OHezAQf2nIiLrZE2OD4H4Cbv3vsPOpEROYw nD+lp2cK9dncepi8vMzRtHd/pz5udKbpB9eE44gO5/p63dcbH4FogUpXUoZKMg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1681476220; 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=JvCjLWfvXF5JPUsHNTTwfsig/8ie0Kb8ZBOZ90qlBnI=; b=fc7gyc01Ma25bFv1P+lyWYADVwMvaUWlakNBXeSfd6AnQaN1Z7elnOX2nlg0Cy87nbCCs8 ucI31HY/+/9XYJpOptna0P8FjJ8mnATR54O4uPREylUtUuzQh0Nr/SucbeTwaFidCNgzss tRebC7nVX9BDqzG/qahyp5tpyP6W+WArYCteKrczNrno7yvinFfAbp24uicSEJNxfk7LpP GyDr2epXYftehJXC8i6nJ9DMn3N+cqO9ueOPlwYNbvZFRELS/EBIe5gCDEPW6D057NS9S3 oQqPaaFYqDla+L60fQ3SWNJEXkLMQCQ0LayWw3jbtlHzibW0WGkjivV4vVEn8g== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1681476220; a=rsa-sha256; cv=none; b=thLW/Q0f+izBM0IuLPxLpDWCzzQucxP7K9eVTui8m4L8BhzJU/+KHC8y1p7Necn52s8uqD CmHbYODPLeXxAzouNR7lw8WpgtZzt/pKqZxSPcXXF3BeKfG2NtPJkn0UxwtElpMF/kJsvX ol5gfuAh7VZUn4oJ0nGkirbr+PAQXkHbKA/S9iVlI6n4n3P04nUx6l/Yvpi1NyOYU2f+K/ fZC1e17/xSMN6qWoFZnyNSK9sGW0IZGa+5ui8zQGqS2KlvxYF2rPYDDjdhau7zc2VhJLAO fc419u04aTKEAKgRXBynBOF2vUG42dMLU76YT5V7hFX/LSjDC+sGxCw7w8XHwg== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (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 did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4Pybj847tVzQ2y; Fri, 14 Apr 2023 12:43:40 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 33ECheIY057849; Fri, 14 Apr 2023 12:43:40 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 33ECheVl057848; Fri, 14 Apr 2023 12:43:40 GMT (envelope-from git) Date: Fri, 14 Apr 2023 12:43:40 GMT Message-Id: <202304141243.33ECheVl057848@gitrepo.freebsd.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org From: =?utf-8?Q?Fernando=20Apestegu=C3=ADa?= Subject: git: a836774703 - main - [Handbook]: Clarify kernel modules on upgrades 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: Sender: owner-dev-commits-doc-all@freebsd.org X-BeenThere: dev-commits-doc-all@freebsd.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: fernape X-Git-Repository: doc X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: a836774703facd9ab8b7bfd64ab1c6116631cdeb Auto-Submitted: auto-generated X-ThisMailContainsUnwantedMimeParts: N The branch main has been updated by fernape: URL: https://cgit.FreeBSD.org/doc/commit/?id=a836774703facd9ab8b7bfd64ab1c6116631cdeb 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 announced. Approved by: doceng@ (carlavilla@, fernape@) Reviewed By: ceri@, jrm@ Differential Revision: https://reviews.freebsd.org/D39474 --- .../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. [[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] ==== @@ -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 <>. 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]]