git: 4bae012609 - main - Update release engineering article to follow git workflow
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Tue, 01 Aug 2023 08:28:59 UTC
The branch main has been updated by carlavilla:
URL: https://cgit.FreeBSD.org/doc/commit/?id=4bae0126093f11fdadb37697f072d3b74b94305a
commit 4bae0126093f11fdadb37697f072d3b74b94305a
Author: Minsoo Choo <minsoochoo0122@proton.me>
AuthorDate: 2023-08-01 08:27:39 +0000
Commit: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org>
CommitDate: 2023-08-01 08:27:39 +0000
Update release engineering article to follow git workflow
Approved by: gjb@ (re), carlavilla (doc)
Differential Revision: https://reviews.freebsd.org/D41091
---
.../content/en/articles/freebsd-releng/_index.adoc | 240 ++++++---------------
shared/en/teams.adoc | 4 +
2 files changed, 74 insertions(+), 170 deletions(-)
diff --git a/documentation/content/en/articles/freebsd-releng/_index.adoc b/documentation/content/en/articles/freebsd-releng/_index.adoc
index 69a43a8d46..d027dba983 100644
--- a/documentation/content/en/articles/freebsd-releng/_index.adoc
+++ b/documentation/content/en/articles/freebsd-releng/_index.adoc
@@ -9,7 +9,7 @@ organizations:
- organization: Rubicon Communications, LLC (Netgate)
webpage: https://www.netgate.com/
description: Describes the approach used by the FreeBSD release engineering team to make production quality releases of the FreeBSD Operating System. It describes the tools available for those interested in producing customized FreeBSD releases for corporate rollouts or commercial productization
-trademarks: ["freebsd", "intel", "general"]
+trademarks: ["freebsd", "intel", "general", "git"]
tags: ["releases", "engineering", "process", "FreeBSD"]
---
@@ -28,13 +28,13 @@ tags: ["releases", "engineering", "process", "FreeBSD"]
:teamPostmaster: FreeBSD Postmaster Team
:teamRe: FreeBSD Release Engineering Team
:teamSecteam: FreeBSD Security Team
-:branchHead: head/
+:branchHead: main
:branchStable: stable/
-:branchStablex: stable/12/
+:branchStablex: stable/13
:branchReleng: releng/
-:branchRelengx: releng/12.0/
-:branchReleasex: release/12.0.0/
-:branchRevision: 12.0
+:branchRelengx: releng/13.0
+:tagReleasex: release/13.0.0
+:branchRevision: 13.0
:images-path: articles/freebsd-releng/
@@ -63,11 +63,6 @@ Abstract
This article describes the release engineering process of the FreeBSD Project.
-[NOTE]
-====
-This document has not yet been updated to describe the current release procedures of the FreeBSD Release Engineering team following the transition from Subversion to Git.
-====
-
'''
toc::[]
@@ -266,13 +261,10 @@ The code slush does not enforce commit approvals to the branch.
The code freeze marks the point in time where all commits to the branch require explicit approval from the {teamRe}.
-The FreeBSD Subversion repository contains several hooks to perform sanity checks before any commit is actually committed to the tree.
+The FreeBSD Git repository contains several hooks to perform sanity checks before any commit is actually committed to the tree.
One of these hooks will evaluate if committing to a particular branch requires specific approval.
-To enforce commit approvals by the {teamRe}, the Release Engineer updates [.filename]#base/svnadmin/conf/approvers#, and commits the change back to the repository.
-Once this is done, any change to the branch must include an "Approved by:" line in the commit message.
-
-The "Approved by:" line must match the second column in [.filename]#base/svnadmin/conf/approvers#, otherwise the commit will be rejected by the repository hooks.
+To enforce commit approvals by the {teamRe}, the Release Engineering Team must approve any changes to the branch, in which case the commit log must include an `Approved by: re (login)` line, where "login" is the login ID of the approver.
[NOTE]
====
@@ -292,7 +284,7 @@ This section describes the changes to the website that should occur as the relea
[NOTE]
====
-The files specified throughout this section are relative to the `head/` branch of the `doc` repository in Subversion.
+The files specified throughout this section are relative to the `{branchHead}` branch of the `doc` repository.
====
[[releng-website-prerelease]]
@@ -325,7 +317,7 @@ When transitioning from `PRERELEASE` to `BETA`, these files need to be updated t
| File to Edit
| What to Change
-|[.filename]#share/releases.adoc#
+|[.filename]#~/shared/releases.adoc#
|Update `betarel-vers` to `BETA__1__`
|[.filename]#~/website/data/en/news/news.toml#
@@ -338,11 +330,7 @@ When transitioning from `PRERELEASE` to `BETA`, these files need to be updated t
|Add the new `BETA`, `RC`, or final `RELEASE` to the template
|===
-Once the {branchRelengx} branch is created, the various release-related documents need to be generated and manually added to the `doc/` repository.
-
-Within [.filename]#release/doc#, invoke to generate [.filename]#errata.html#, [.filename]#hardware.html#, [.filename]#readme.html#, and [.filename]#relnotes.html# pages, which are then added to [.filename]#doc/head/en_US.ISO8859-1/htdocs/releases/X.YR/#, where _X.Y_ represents the major and minor version number of the release.
-
-The `fbsd:nokeywords` property must be set to `on` on the newly-added files before the pre-commit hooks will allow them to be added to the repository.
+Once the {branchRelengx} branch is created, the various release-related documents need to be added to the `doc/` repository.
[NOTE]
====
@@ -380,14 +368,19 @@ See <<releng-building>> for information on building the `ALPHA` images.
When creating the {branchStable} branch, several changes are required in both the new {branchStable} branch and the {branchHead} branch.
The files listed are relative to the repository root.
-To create the new {branchStablex} branch in Subversion:
+To create the new {branchStablex} branch in Git:
+
+[NOTE]
+====
+Make sure that you are in the {branchHead} branch
+====
[source,shell,subs="attributes"]
....
-% svn cp ^/head {branchStablex}
+% git checkout -b {branchStablex}
....
-Once the {branchStablex} branch has been committed, make the following edits:
+Once the {branchStablex} branch has been created, make the following edits:
[.informaltable]
[cols="1,1", frame="none", options="header"]
@@ -395,10 +388,10 @@ Once the {branchStablex} branch has been committed, make the following edits:
| File to Edit
| What to Change
-|[.filename]#stable/12/UPDATING#
+|[.filename]#UPDATING#
|Update the FreeBSD version, and remove the notice about `WITNESS`
-|[.filename]#stable/12/contrib/jemalloc/include/jemalloc/jemalloc_FreeBSD.h#
+|[.filename]#contrib/jemalloc/include/jemalloc/jemalloc_FreeBSD.h#
a|
[source,shell,subs="attributes"]
@@ -408,37 +401,37 @@ a|
#endif
....
-|[.filename]#stable/12/lib/clang/llvm.build.mk#
+|[.filename]#lib/clang/llvm.build.mk#
|Uncomment `-DNDEBUG`
-|[.filename]#stable/12/sys/\*/conf/GENERIC*#
+|[.filename]#sys/\*/conf/GENERIC*#
|Remove debugging support
-|[.filename]#stable/12/sys/*/conf/MINIMAL#
+|[.filename]#sys/*/conf/MINIMAL#
|Remove debugging support
-|[.filename]#stable/12/release/release.conf.sample#
+|[.filename]#release/release.conf.sample#
|Update `SRCBRANCH`
-|[.filename]#stable/12/sys/*/conf/GENERIC-NODEBUG#
+|[.filename]#sys/*/conf/GENERIC-NODEBUG#
|Remove these kernel configurations
-|[.filename]#stable/12/sys/arm/conf/std.arm*#
+|[.filename]#sys/arm/conf/std.arm*#
|Remove debugging options
-|[.filename]#stable/12/sys/conf/newvers.sh#
+|[.filename]#sys/conf/newvers.sh#
|Update the `BRANCH` value to reflect `BETA1`
-|[.filename]#stable/12/share/mk/src.opts.mk#
+|[.filename]#share/mk/src.opts.mk#
|Move `REPRODUCIBLE_BUILD` from `\__DEFAULT_NO_OPTIONS` to `__DEFAULT_YES_OPTIONS`
-|[.filename]#stable/12/share/mk/src.opts.mk#
+|[.filename]#share/mk/src.opts.mk#
|Move `LLVM_ASSERTIONS` from `\__DEFAULT_YES_OPTIONS` to `__DEFAULT_NO_OPTIONS` (FreeBSD 13.x and later only)
-|[.filename]#stable/12/libexec/rc/rc.conf#
+|[.filename]#libexec/rc/rc.conf#
|Set `dumpdev` from `AUTO` to `NO` (it is configurable via for those that want it enabled by default)
-|[.filename]#stable/12/release/Makefile#
+|[.filename]#release/Makefile#
|Remove the `debug.witness.trace` entries
|===
@@ -450,34 +443,34 @@ Then in the {branchHead} branch, which will now become a new major version:
| File to Edit
| What to Change
-|[.filename]#head/UPDATING#
+|[.filename]#UPDATING#
|Update the FreeBSD version
-|[.filename]#head/sys/conf/newvers.sh#
+|[.filename]#sys/conf/newvers.sh#
|Update the `BRANCH` value to reflect `CURRENT`, and increment `REVISION`
-|[.filename]#head/Makefile.inc1#
+|[.filename]#Makefile.inc1#
|Update `TARGET_TRIPLE` and `MACHINE_TRIPLE`
-|[.filename]#head/sys/sys/param.h#
+|[.filename]#sys/sys/param.h#
|Update `__FreeBSD_version`
-|[.filename]#head/gnu/usr.bin/cc/cc_tools/freebsd-native.h#
+|[.filename]#gnu/usr.bin/cc/cc_tools/freebsd-native.h#
|Update `FBSD_MAJOR` and `FBSD_CC_VER`
-|[.filename]#head/contrib/gcc/config.gcc#
+|[.filename]#contrib/gcc/config.gcc#
|Append the `freebsdversion.h` section
-|[.filename]#head/lib/clang/llvm.build.mk#
+|[.filename]#lib/clang/llvm.build.mk#
|Update the value of `OS_VERSION`
-|[.filename]#head/lib/clang/freebsd_cc_version.h#
+|[.filename]#lib/clang/freebsd_cc_version.h#
|Update `FREEBSD_CC_VERSION`
-|[.filename]#head/lib/clang/include/lld/Common/Version.inc#
+|[.filename]#lib/clang/include/lld/Common/Version.inc#
|Update `LLD_REVISION_STRING`
-|[.filename]#head/Makefile.libcompat#
+|[.filename]#Makefile.libcompat#
|Update `LIB32CPUFLAGS`
|===
@@ -516,13 +509,7 @@ These files are all relative to the top-most level of the stable branch:
Following the code slush, the next phase of the release cycle is the code freeze.
This is the point at which all commits to the stable branch require explicit approval from the {teamRe}.
-This is enforced by pre-commit hooks in the Subversion repository by editing [.filename]#base/svnadmin/conf/approvers# to include a regular expression matching the {branchStablex} branch for the release:
-
-[.programlisting,subs="attributes"]
-....
-^/{branchStablex} re
-^/{branchRelengx} re
-....
+This is enforced by {git-admin-email} who handles the repository.
[NOTE]
====
@@ -544,9 +531,14 @@ This is a multi-step process that must be done in a specific order, to avoid ano
The paths listed below are relative to the repository root.
The order of commits and what to change are:
+[NOTE]
+====
+Make sure that you are in the {branchStablex} branch
+====
+
[source,shell,subs="attributes"]
....
-% svn cp ^/{branchStablex} {branchRelengx}
+% git checkout -b {branchRelengx}
....
[.informaltable]
@@ -555,41 +547,39 @@ The order of commits and what to change are:
| File to Edit
| What to Change
-|[.filename]#releng/12.0/sys/conf/newvers.sh#
+|[.filename]#sys/conf/newvers.sh#
|Change `BETA__X__` to `RC1`
-|[.filename]#releng/12.0/sys/sys/param.h#
+|[.filename]#sys/sys/param.h#
|Update `__FreeBSD_version`
-|[.filename]#releng/12.0/sys/conf/kern.opts.mk
+|[.filename]#sys/conf/kern.opts.mk#
|Move `REPRODUCIBLE_BUILD` from `__DEFAULT_NO_OPTIONS` to `__DEFAULT_YES_OPTIONS`
-|[.filename]#releng/12.0/etc/pkg/FreeBSD.conf#
+|[.filename]#etc/pkg/FreeBSD.conf#
|Replace `latest` with `quarterly` as the default package repository location
-|[.filename]#releng/12.0/release/pkg_repos/release-dvd.conf#
+|[.filename]#release/pkg_repos/release-dvd.conf#
|Replace `latest` with `quarterly` as the default package repository location
-|[.filename]#stable/12/sys/conf/newvers.sh#
+|[.filename]#sys/conf/newvers.sh#
|Update `BETA__X__` with `PRERELEASE`
-|[.filename]#stable/12/sys/sys/param.h#
+|[.filename]#sys/sys/param.h#
|Update `__FreeBSD_version`
-
-|[.filename]#svnadmin/conf/approvers#
-|Add a new approvers line for the releng branch as was done for the stable branch
|===
+Then, {git-admin-email} adds new approvers for the releng branch as did for the stable branch.
+
[source,shell,subs="attributes"]
....
-% svn propdel -R svn:mergeinfo {branchRelengx}
-% svn commit {branchRelengx}
-% svn commit {branchStablex}
+% git add .
+% git commit
....
Now that two new `__FreeBSD_version` values exist, also update [.filename]#~/documentation/content/en/books/porters-handbook/versions/chapter.adoc# in the Documentation Project repository.
-After the first `RC` build has completed and tested, the {branchStable} branch can be "thawed" by removing (or commenting) the ^/{branchStablex} entry in [.filename]#svnadmin/conf/approvers#.
+After the first `RC` build has completed and tested, the {branchStable} branch can be "thawed" by {git-admin-email}.
Following the availability of the first `RC`, {teamBugmeister} should be emailed to add the new FreeBSD `-RELEASE` to the `versions` available in the drop-down menu shown in the bug tracker.
@@ -601,11 +591,6 @@ This section describes the general procedures producing FreeBSD development snap
[[releng-build-scripts]]
=== Release Build Scripts
-This section describes the build scripts used by {teamRe} to produce development snapshots and releases.
-
-[[releng-build-scripts-single]]
-==== The [.filename]#release.sh# Script
-
Prior to FreeBSD 9.0-RELEASE, [.filename]#src/release/Makefile# was updated to support , and the [.filename]#src/release/generate-release.sh# script was introduced as a wrapper to automate invoking the targets.
Prior to FreeBSD 9.2-RELEASE, [.filename]#src/release/release.sh# was introduced, which heavily based on [.filename]#src/release/generate-release.sh# included support to specify configuration files to override various options and environment variables.
@@ -638,98 +623,9 @@ Then invoke [.filename]#src/release/release.sh# as:
See and [.filename]#src/release/release.conf.sample# for more details and example usage.
-[[releng-build-scripts-multiple]]
-==== The [.filename]#thermite.sh# Wrapper Script
-
-To make cross building the full set of architectures supported on a given branch faster, easier, and reduce human error factors, a wrapper script around [.filename]#src/release/release.sh# was written to iterate through the various combinations of architectures and invoke [.filename]#src/release/release.sh# using a configuration file specific to that architecture.
-
-The wrapper script is called [.filename]#thermite.sh#, which is available in the FreeBSD Subversion repository at `svn://svn.freebsd.org/base/user/gjb/thermite/`, in addition to configuration files used to build {branchHead} and {branchStablex} development snapshots.
-
-Using [.filename]#thermite.sh# is covered in <<releng-build-snapshot>> and <<releng-build-release>>.
-
-Each architecture and individual kernel have their own configuration file used by [.filename]#release.sh#.
-Each branch has its own [.filename]#defaults-X.conf# configuration which contains entries common throughout each architecture, where overrides or special variables are set and/or overridden in the per-build files.
-
-The per-build configuration file naming scheme is in the form of [.filename]#${revision}-${TARGET_ARCH}-${KERNCONF}-${type}.conf#, where the uppercase variables are equivalent to what uses in the build system, and lowercase variables are set within the configuration files, mapping to the major version of the respective branch.
-
-Each branch also has its own [.filename]#builds-X.conf# configuration, which is used by [.filename]#thermite.sh#. The [.filename]#thermite.sh# script iterates through each ${revision}, ${TARGET_ARCH}, ${KERNCONF}, and ${type} value, creating a master list of what to build.
-However, a given combination from the list will only be built if the respective configuration file exists, which is where the naming scheme above is relevant.
-
-There are two paths of file sourcing:
-
-* [.filename]#builds-12.conf# - [.filename]#main.conf#
-+
-This controls [.filename]#thermite.sh# behavior
-* [.filename]#12-amd64-GENERIC-snap.conf# - [.filename]#defaults-12.conf# - [.filename]#main.conf#
-+
-This controls [.filename]#release/release.sh# behavior within the build
-
-[NOTE]
-====
-The [.filename]#builds-12.conf#, [.filename]#defaults-12.conf#, and [.filename]#main.conf# configuration files exist to reduce repetition between the various per-build files.
-====
-
-[[releng-build-snapshot]]
-=== Building FreeBSD Development Snapshots
-
-The official release build machines have a specific filesystem layout, which using ZFS, [.filename]#thermite.sh# takes heavy advantage of with clones and snapshots, ensuring a pristine build environment.
-
-The build scripts reside in [.filename]#/releng/scripts-snapshot/scripts# or [.filename]#/releng/scripts-release/scripts# respectively, to avoid collisions between an `RC` build from a releng branch versus a `STABLE` snapshot from the respective stable branch.
-
-A separate dataset exists for the final build images, [.filename]#/snap/ftp#. This directory contains both snapshots and releases directories.
-They are only used if the `EVERYTHINGISFINE` variable is defined in [.filename]#main.conf#.
-
-[NOTE]
-====
-The `EVERYTHINGISFINE` variable name was chosen to avoid colliding with a variable that might be possibly set in the user environment, accidentally enabling the behavior that depends on it being defined.
-====
-
-As [.filename]#thermite.sh# iterates through the master list of combinations and locates the per-build configuration file, a ZFS dataset is created under [.filename]#/releng#, such as [.filename]#/releng/12-amd64-GENERIC-snap#.
-The `src/`, `ports/`, and `doc/` trees are checked out to separate ZFS datasets, such as [.filename]#/releng/12-src-snap#, which are then cloned and mounted into the respective build datasets.
-This is done to avoid checking out a given tree more than once.
-
-Assuming these filesystem paths, [.filename]#thermite.sh# would be invoked as:
-
-[source,shell,subs="attributes"]
-....
-# cd /releng/scripts-snapshot/scripts
-# ./setrev.sh -b {branchStablex}
-# ./zfs-cleanup.sh -c ./builds-12.conf
-# ./thermite.sh -c ./builds-12.conf
-....
-
-Once the builds have completed, additional helper scripts are available to generate development snapshot emails which are sent to the `freebsd-snapshots@freebsd.org` mailing list:
-
-[source,shell,subs="attributes"]
-....
-# cd /releng/scripts-snapshot/scripts
-# ./get-checksums.sh -c ./builds-12.conf | ./generate-email.pl > snapshot-12-mail
-....
-
-[NOTE]
-====
-The generated output should be double-checked for correctness, and the email itself should be PGP signed, in-line.
-====
-
-[NOTE]
-====
-These helper scripts only apply to development snapshot builds.
-Announcements during the release cycle (excluding the final release announcement) are created from an email template.
-A sample of the email template currently used can be found link:here[here].
-====
-
[[releng-build-release]]
=== Building FreeBSD Releases
-Similar to building FreeBSD development snapshots, [.filename]#thermite.sh# would be invoked the same way.
-The difference between development snapshots and release builds, `BETA` and `RC` included, is that the configuration files must be named with `release` instead of `snap` as the type, as mentioned above.
-
-In addition, the `BUILDTYPE` and `types` must be changed from `snap` to `release` in [.filename]#defaults-12.conf# and [.filename]#builds-12.conf#, respectively.
-
-When building `BETA`, `RC`, and the final `RELEASE`, also statically set `BUILDSVNREV` to the revision on the branch reflecting the name change, `BUILDDATE` to the date the builds are started in `YYYYMMDD` format.
-If the `doc/` and `ports/` trees have been tagged, also set `PORTBRANCH` and `DOCBRANCH` to the relevant tag path in the Subversion repository, replacing `HEAD` with the last changed revision.
-Also set `releasesrc` in [.filename]#builds-12.conf# to the relevant branch, such as {branchStablex} or {branchRelengx}.
-
During the release cycle, a copy of [.filename]#CHECKSUM.SHA512# and [.filename]#CHECKSUM.SHA256# for each architecture are stored in the {teamRe} internal repository in addition to being included in the various announcement emails.
Each [.filename]#MANIFEST# containing the hashes of [.filename]#base.txz#, [.filename]#kernel.txz#, etc. are added to package:misc/freebsd-release-manifests[] in the Ports Collection, as well.
@@ -751,14 +647,18 @@ In preparation for the release build, several files need to be updated:
|Replace `__FreeBSD_version` with the value in [.filename]#sys/sys/param.h#
|===
-After building the final `RELEASE`, the {branchRelengx} branch is tagged as {branchReleasex} using the revision from which the `RELEASE` was built.
-Similar to creating the {branchStablex} and {branchRelengx} branches, this is done with `svn cp`.
+After building the final `RELEASE`, the {branchRelengx} branch is tagged as {tagReleasex} using the revision from which the `RELEASE` was built.
+Similar to creating the {branchStablex} and {branchRelengx} branches, this is done with `git tag`.
From the repository root:
+[NOTE]
+====
+Make sure that you are in the {branchRelengx} branch
+====
+
[source,shell,subs="attributes"]
....
-% svn cp ^/{branchRelengx}@r306420 {branchReleasex}
-% svn commit {branchReleasex}
+% git tag {tagReleasex}
....
[[releng-mirrors]]
@@ -846,7 +746,7 @@ Once the {branchReleng} branch has been handed over to the {teamSecteam} as desc
[[releng-wrapup-handoff]]
=== Handoff to the {teamSecteam}
-Roughly two weeks following the release, the Release Engineer updates [.filename]#svnadmin/conf/approvers# changing the approver column from `re` to `(so|security-officer)` for the {branchRelengx} branch.
+Roughly two weeks following the release, the Release Engineer updates the Git repository changing the approver from the Release engineering team to the security officer for the {branchRelengx} branch.
[[releng-eol]]
== Release End-of-Life
diff --git a/shared/en/teams.adoc b/shared/en/teams.adoc
index f433571100..194f231149 100644
--- a/shared/en/teams.adoc
+++ b/shared/en/teams.adoc
@@ -59,6 +59,10 @@
:mirror-admin-email: mirror-admin@FreeBSD.org
:mirror-admin: {mirror-admin-name} <{mirror-admin-email}>
+:git-admin-name: Git administrators
+:git-admin-email: gitadm@FreeBSD.org
+:git-admin: {git-admin-name} <{git-admin-email}>
+
:pcvs-name: CVS ports Repository Meisters
:pcvs-email: pcvs@FreeBSD.org
:pcvs: {pcvs-name} <{pcvs-email}>