Index: head/en_US.ISO8859-1/articles/freebsd-releng/article.xml =================================================================== --- head/en_US.ISO8859-1/articles/freebsd-releng/article.xml (revision 52376) +++ head/en_US.ISO8859-1/articles/freebsd-releng/article.xml (revision 52377) @@ -1,473 +1,473 @@ head/"> stable/"> -stable/11/"> +stable/12/"> releng/"> -releng/11.0/"> -release/11.0.0/"> -11.0"> +releng/12.0/"> +release/12.0.0/"> +12.0"> ]>
&os; Release Engineering Glen Barber The &os; Foundation
gjb@FreeBSD.org
 &tm-attrib.freebsd; &tm-attrib.intel; &tm-attrib.general; $FreeBSD$ This article describes the release engineering process of the &os; Project. Introduction to the &os; Release Engineering Process Development of &os; has a very specific workflow. In general, all changes to the &os; base system are committed to the &branch.head; branch, which reflects the top of the source tree. After a reasonable testing period, changes can then be merged to the &branch.stable; branches. The default minimum timeframe before merging to &branch.stable; branches is three (3) days. Although a general rule to wait a minimum of three days before merging from &branch.head;, there are a few special circumstances where an immediate merge may be necessary, such as a critical security fix, or a bug fix that directly inhibits the release build process. After several months, and the number of changes in the &branch.stable; branch have grown significantly, it is time to release the next version of &os;. These releases have been historically referred to as point releases. In between releases from the &branch.stable; branches, approximately every two (2) years, a release will be cut directly from &branch.head;. These releases have been historically referred to as dot-zero releases. This article will highlight the workflow and responsibilities of the &team.re; for both dot-zero and point' releases. The following sections of this article describe: General information and preparation before starting the release cycle. Website Changes During the Release Cycle Terminology and general information, such as the code slush and code freeze, used throughout this document. The Release Engineering process for a dot-zero release. The Release Engineering process for a point release. Information related to the specific procedures to build installation medium. Procedures to publish installation medium. Wrapping up the release cycle. General Information and Preparation Approximately two months before the start of the release cycle, the &team.re; decides on a schedule for the release. The schedule includes the various milestone points of the release cycle, such as freeze dates, branch dates, and build dates. For example: Milestone Anticipated Date &branch.head; slush: May 27, 2016 &branch.head; freeze: June 10, 2016 &branch.head; KBI freeze: June 24, 2016 doc/ tree slush [1]: June 24, 2016 Ports quarterly branch [2]: July 1, 2016 &branch.stablex; branch: July 8, 2016 doc/ tree tag [3]: July 8, 2016 BETA1 build starts: July 8, 2016 &branch.head; thaw: July 9, 2016 BETA2 build starts: July 15, 2016 BETA3 build starts [*]: July 22, 2016 &branch.relengx; branch: July 29, 2016 RC1 build starts: July 29, 2016 &branch.stablex; thaw: July 30, 2016 RC2 build starts: August 5, 2016 Final Ports package builds [4]: August 6, 2016 Ports release tag: August 12, 2016 RC3 build starts [*]: August 12, 2016 RELEASE build starts: August 19, 2016 RELEASE announcement: September 2, 2016 Items marked with "[*]" are "as needed". The doc/ tree slush is coordinated by the &team.doceng;. The Ports quarterly branch used is determined by when the final RC build is planned. A new quarterly branch is created on the first day of the quarter, so this metric should be used when taking the release cycle milestones into account. The quarterly branch is created by the &team.portmgr;. The doc/ tree is tagged by the &team.doceng;. The final Ports package build is done by the &team.portmgr; after the final (or what is expected to be final) RC build. If the release is being created from an existing &branch.stable; branch, the KBI freeze date can be excluded, since the KBI is already considered frozen on established &branch.stable; branches. When writing the release cycle schedule, a number of things need to be taken into consideration, in particular milestones where the target date depends on predefined milestones upon which there is a dependency. For example, the Ports Collection release tag originates from the active quarterly branch at the time of the last RC. This in part defines which quarterly branch is used, when the release tag can happen, and what revision of the ports tree is used for the final RELEASE build. After general agreement on the schedule, the &team.re; emails the schedule to the &os; Developers. It is somewhat typical that many developers will inform the &team.re; about various works-in-progress. In some cases, an extension for the in-progress work will be requested, and in other cases, a request for blanket approval to a particular subset of the tree will be made. When such requests are made, it is important to make sure timelines (even if estimated) are discussed. For blanket approvals, the length of time for the blanket approval should be made clear. For example, a &os; developer may request blanket approvals from the start of the code slush until the start of the RC builds. In order to keep track of blanket approvals, the &team.re; uses an internal repository to keep a running log of such requests, which defines the area upon which a blanket approval was granted, the author(s), when the blanket approval expires, and the reason the approval was granted. One example of this is granting blanket approval to release/doc/ to all &team.re; members until the final RC to update the release notes and other release-related documentation. The &team.re; also uses this repository to track pending approval requests that are received just prior to starting various builds during the release cycle, which the Release Engineer specifies the cutoff period with an email to the &os; developers. Depending on the underlying set of code in question, and the overall impact the set of code has on &os; as a whole, such requests may be approved or denied by the &team.re;. The same applies to work-in-progress extensions. For example, in-progress work for a new device driver that is otherwise isolated from the rest of the tree may be granted an extension. A new scheduler, however, may not be feasible, especially if such dramatic changes do not exist in another branch. The schedule is also added to the Project website, in the doc/ repository, in head/en_US.ISO8859-1/htdocs/releases/&branch.revision;R/schedule.xml. This file is continuously updated as the release cycle progresses. In most cases, the schedule.xml can be copied from a prior release and updated accordingly. In addition to adding schedule.xml to the website, head/share/xml/navibar.ent and head/share/xml/release.ent are also updated to add the link to the schedule to various subpages, as well as enabling the link to the schedule on the Project website index page. The schedule is also linked from head/en_US.ISO8859-1/htdocs/releng/index.xml. Approximately one month prior to the scheduled code slush, the &team.re; sends a reminder email to the &os; Developers. Once the first builds of the release cycle are available, update the beta.local.where entity in head/en_US.ISO8859-1/htdocs/releases/&branch.revision;R/schedule.xml. replacing IGNORE with INCLUDE. If two parallel release cycles are happening at once, the beta2.local.where entity may be used instead. &release.terminology; &release.website; &release.major.version; &release.minor.version; &release.building; &release.mirrors; Wrapping up the Release Cycle This section describes general post-release tasks. Post-Release Errata Notices As the release cycle approaches conclusion, it is common to have several EN (Errata Notice) candidates to address issues that were discovered late in the cycle. Following the release, the &team.re; and the &team.secteam; revisit changes that were not approved prior to the final release, and depending on the scope of the change in question, may issue an EN. The actual process of issuing ENs is handled by the &team.secteam;. Handoff to the &team.secteam; Roughly two weeks following the release, the Release Engineer updates svnadmin/conf/approvers changing the approver column from re to (so|security-officer) for the &branch.relengx; branch.
Index: head/en_US.ISO8859-1/articles/freebsd-releng/releng-building.xml =================================================================== --- head/en_US.ISO8859-1/articles/freebsd-releng/releng-building.xml (revision 52376) +++ head/en_US.ISO8859-1/articles/freebsd-releng/releng-building.xml (revision 52377) @@ -1,281 +1,281 @@ Building &os; Installation Media This section describes the general procedures producing &os; development snapshots and releases. Release Build Scripts This section describes the build scripts used by &team.re; to produce development snapshots and releases. The <filename>release.sh</filename> Script Prior to &os; 9.0-RELEASE, src/release/Makefile was updated to support &man.bsdinstall.8;, and the src/release/generate-release.sh script was introduced as a wrapper to automate invoking the &man.release.7; targets. Prior to &os; 9.2-RELEASE, src/release/release.sh was introduced, which heavily based on src/release/generate-release.sh included support to specify configuration files to override various options and environment variables. Support for configuration files provided support for cross building each architecture for a release by specifying a separate configuration file for each invocation. As a brief example of using src/release/release.sh to build a single release in /scratch: &prompt.root; /bin/sh /usr/src/release/release.sh As a brief example of using src/release/release.sh to build a single, cross-built release using a different target directory, create a custom release.conf containing: # release.sh configuration for powerpc/powerpc64 CHROOTDIR="/scratch-powerpc64" TARGET="powerpc" TARGET_ARCH="powerpc64" KERNEL="GENERIC64" Then invoke src/release/release.sh as: &prompt.root; /bin/sh /usr/src/release/release.sh -c $HOME/release.conf See &man.release.7; and src/release/release.conf.sample for more details and example usage. The <filename>thermite.sh</filename> Wrapper Script In order 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 src/release/release.sh was written to iterate through the various combinations of architectures and invoke src/release/release.sh using a configuration file specific to that architecture. The wrapper script is called thermite.sh, which is available in the &os; Subversion repository at svn://svn.freebsd.org/base/user/gjb/thermite/, in addition to configuration files used to build &branch.head; and &branch.stablex; development snapshots. Using thermite.sh is covered in and . Each architecture and individual kernel have their own configuration file used by release.sh. Each branch has its own 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 ${revision}-${TARGET_ARCH}-${KERNCONF}-${type}.conf, where the uppercase variables are equivalent to what &man.make.1; 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 builds-X.conf configuration, which is used by thermite.sh. The 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: - builds-11.conf + builds-12.conf -> main.conf This controls thermite.sh behavior - 11-amd64-GENERIC-snap.conf + 12-amd64-GENERIC-snap.conf -> - defaults-11.conf + defaults-12.conf -> main.conf This controls release/release.sh behavior within the build &man.chroot.8; The - builds-11.conf, - defaults-11.conf, + builds-12.conf, + defaults-12.conf, and main.conf configuration files exist to reduce repetition between the various per-build files. Building &os; Development Snapshots The official release build machines have a specific filesystem layout, which using ZFS, thermite.sh takes heavy advantage of with clones and snapshots, ensuring a pristine build environment. The build scripts reside in /releng/scripts-snapshot/scripts or /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, /snap/ftp. This directory contains both snapshots and releases directories. They are only used if the EVERYTHINGISFINE variable is defined in main.conf. 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 thermite.sh iterates through the master list of combinations and locates the per-build configuration file, a ZFS dataset is created under /releng, such as /releng/12-amd64-GENERIC-snap. The src/, ports/, and doc/ trees are checked out to separate ZFS datasets, such as /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, thermite.sh would be invoked as: &prompt.root; cd /releng/scripts-snapshot/scripts &prompt.root; ./setrev.sh -b &branch.stablex; -&prompt.root; ./zfs-setup.sh -c ./builds-11.conf -&prompt.root; ./thermite.sh -c ./builds-11.conf +&prompt.root; ./zfs-setup.sh -c ./builds-12.conf +&prompt.root; ./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: &prompt.root; cd /releng/scripts-snapshot/scripts -&prompt.root; ./get-checksums.sh -c ./builds-11.conf | ./generate-email.pl > snapshot-11-mail +&prompt.root; ./get-checksums.sh -c ./builds-12.conf | ./generate-email.pl > snapshot-12-mail The generated output should be double-checked for correctness, and the email itself should be PGP signed, in-line. 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 here. Building &os; Releases Similar to building &os; development snapshots, thermite.sh would be invoked the same way. The difference between development snapshots and release builds, BETA and RC included, is that the &man.chroot.8; 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 - defaults-11.conf + defaults-12.conf and - builds-11.conf, + 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 - builds-11.conf + builds-12.conf to the relevant branch, such as &branch.stablex; or &branch.relengx;. During the release cycle, a copy of CHECKSUM.SHA512 and CHECKSUM.SHA256 for each architecture are stored in the &team.re; internal repository in addition to being included in the various announcement emails. Each MANIFEST containing the hashes of base.txz, kernel.txz, etc. are added to misc/freebsd-release-manifests in the Ports Collection, as well. After building the final RELEASE, the &branch.relengx; branch is tagged as &branch.releasex; using the revision from which the RELEASE was built. Similar to creating the &branch.stablex; and &branch.relengx; branches, this is done with svn cp. From the repository root: &prompt.user; svn cp ^/&branch.relengx;@r306420 &branch.releasex; &prompt.user; svn commit &branch.releasex; Index: head/en_US.ISO8859-1/articles/freebsd-releng/releng-major-version.xml =================================================================== --- head/en_US.ISO8859-1/articles/freebsd-releng/releng-major-version.xml (revision 52376) +++ head/en_US.ISO8859-1/articles/freebsd-releng/releng-major-version.xml (revision 52377) @@ -1,194 +1,194 @@ Release from &branch.head; This section describes the general procedures of the &os; release cycle from the &branch.head; branch. &os; <quote><literal>ALPHA</literal></quote> Builds Starting with the &os; 10.0-RELEASE cycle, the notion of ALPHA builds was introduced. Unlike the BETA and RC builds, ALPHA builds are not included in the &os; Release schedule. The idea behind ALPHA builds is to provide regular &os;-provided builds before the creation of the &branch.stable; branch. &os; ALPHA snapshots should be built approximately once a week. For the first ALPHA build, the BRANCH value in sys/conf/newvers.sh needs to be changed from CURRENT to ALPHA1. For subsequent ALPHA builds, increment each ALPHAN value by one. See for information on building the ALPHA images. Creating the &branch.stablex; Branch When creating the &branch.stable; branch, several changes are required in both the new &branch.stable; branch and the &branch.head; branch. The files listed are relative to the repository root. To create the new &branch.stablex; branch in Subversion: &prompt.user; svn cp ^/head &branch.stablex; Once the &branch.stablex; branch has been committed, make the following edits: File to Edit What to Change - stable/11/UPDATING + stable/12/UPDATING Update the &os; version, and remove the notice about WITNESS - stable/11/contrib/jemalloc/include/jemalloc/jemalloc_FreeBSD.h + stable/12/contrib/jemalloc/include/jemalloc/jemalloc_FreeBSD.h #ifndef MALLOC_PRODUCTION #define MALLOC_PRODUCTION #endif - stable/11/sys/*/conf/GENERIC* + stable/12/sys/*/conf/GENERIC* Remove debugging support - stable/11/release/release.conf.sample + stable/12/release/release.conf.sample Update SRCBRANCH - stable/11/sys/*/conf/GENERIC-NODEBUG + stable/12/sys/*/conf/GENERIC-NODEBUG Remove these kernel configurations - stable/11/sys/conf/newvers.sh + stable/12/sys/conf/newvers.sh Update the BRANCH value to reflect BETA1 Then in the &branch.head; branch, which will now become a new major version: File to Edit What to Change head/UPDATING Update the &os; version head/sys/conf/newvers.sh Update the BRANCH value to reflect CURRENT, and increment REVISION head/Makefile.inc1 Update TARGET_TRIPLE and MACHINE_TRIPLE head/sys/sys/param.h Update __FreeBSD_version head/gnu/usr.bin/cc/cc_tools/freebsd-native.h Update FBSD_MAJOR and FBSD_CC_VER head/contrib/gcc/config.gcc Append the freebsd<version>.h section head/lib/clang/llvm.build.mk Update the value of OS_VERSION head/release/Makefile Remove the debug.witness.trace entries head/release/doc/en_US.ISO8859-1/readme/article.xml Replace &a.current; with &a.stable; ?> head/release/doc/share/xml/release.ent ?> head/lib/clang/llvm.build.mk Uncomment -DNDEBUG head/lib/clang/freebsd_cc_version.h Update FREEBSD_CC_VERSION Index: head/en_US.ISO8859-1/articles/freebsd-releng/releng-minor-version.xml =================================================================== --- head/en_US.ISO8859-1/articles/freebsd-releng/releng-minor-version.xml (revision 52376) +++ head/en_US.ISO8859-1/articles/freebsd-releng/releng-minor-version.xml (revision 52377) @@ -1,175 +1,175 @@ Release from &branch.stable; This section describes the general procedures of the &os; release cycle from an extablished &branch.stable; branch. &os; <literal>stable</literal> Branch Code Slush In preparation for the code freeze on a stable branch, several files need to be updated to reflect the release cycle is officially in progress. These files are all relative to the top-most level of the stable branch: File to Edit What to Change sys/conf/newvers.sh Update the BRANCH value to reflect PRERELEASE Makefile.inc1 Update TARGET_TRIPLE &os; <literal>BETA</literal> Builds 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 &team.re;. This is enforced by pre-commit hooks in the Subversion repository by editing base/svnadmin/conf/approvers to include a regular expression matching the &branch.stablex; branch for the release: ^/&branch.stablex; re There are two general exceptions to requiring commit approval during the release cycle. The first is any change that needs to be committed by the Release Engineer in order to proceed with the day-to-day workflow of the release cycle, the other is security fixes that may occur during the release cycle. Once the code freeze is in effect, the next build from the branch is labeled BETA1. This is done by updating the BRANCH value in sys/conf/newvers.sh from PRERELEASE to BETA1. Once this is done, the first set of BETA builds are started. Subsequent BETA builds do not require updates to any files other than sys/conf/newvers.sh, incrementing the BETA build number. Creating the &branch.relengx; Branch When the first RC (Release Candidate) build is ready to begin, the &branch.releng; branch is created. This is a multi-step process that must be done in a specific order, in order to avoid anomalies such as overlaps with __FreeBSD_version values, for example. The paths listed below are relative to the repository root. The order of commits and what to change are: &prompt.user; svn cp ^/&branch.stablex; &branch.relengx; File to Edit What to Change - releng/11.0/sys/conf/newvers.sh + releng/12.0/sys/conf/newvers.sh Change BETAX to RC1 - releng/11.0/sys/sys/param.h + releng/12.0/sys/sys/param.h Update __FreeBSD_version - releng/11.0/etc/pkg/FreeBSD.conf + releng/12.0/etc/pkg/FreeBSD.conf Replace latest with quarterly as the default package repository location - releng/11.0/release/pkg_repos/release-dvd.conf + releng/12.0/release/pkg_repos/release-dvd.conf Replace latest with quarterly as the default package repository location - stable/11/sys/conf/newvers.sh + stable/12/sys/conf/newvers.sh Update BETAX with PRERELEASE - stable/11/sys/sys/param.h + stable/12/sys/sys/param.h Update __FreeBSD_version svnadmin/conf/approvers Add a new approvers line for the releng branch as was done for the stable branch &prompt.user; svn propdel -R svn:mergeinfo &branch.relengx; &prompt.user; svn commit &branch.relengx; &prompt.user; svn commit &branch.stablex; Now that two new __FreeBSD_version values exist, also update head/en_US.ISO8859-1/books/porters-handbook/versions/chapter.xml in the Documentation Project repository. After the first RC build has completed and tested, the &branch.stable; branch can be thawed by removing (or commenting) the ^/&branch.stablex; entry in svnadmin/conf/approvers. Following the availability of the first RC, &team.bugmeister; should be emailed to add the new &os; -RELEASE to the versions available in the drop-down menu shown in the bug tracker. Index: head/en_US.ISO8859-1/articles/freebsd-releng/releng-website.xml =================================================================== --- head/en_US.ISO8859-1/articles/freebsd-releng/releng-website.xml (revision 52376) +++ head/en_US.ISO8859-1/articles/freebsd-releng/releng-website.xml (revision 52377) @@ -1,149 +1,149 @@ Website Changes During the Release Cycle This section describes the changes to the website that should occur as the release cycle progresses. The files specified throughout this section are relative to the head/ branch of the doc repository in Subversion. Website Changes Before the Release Cycle Begins When the release cycle schedule is available, these files need to be updated to enable various different functionalities on the &os; Project website: File to Edit What to Change share/xml/release.ent Change beta.upcoming from IGNORE to INCLUDE share/xml/release.ent Change % beta.upcoming from IGNORE to INCLUDE share/xml/release.ent Change beta.testing from IGNORE to INCLUDE share/xml/release.ent Change % beta.testing from IGNORE to INCLUDE Website Changes During <literal>BETA</literal> or <literal>RC</literal> When transitioning from PRERELEASE to BETA, these files need to be updated to enable the "Help Test" block on the download page. All files are relative to head/ in the doc repository: File to Edit What to Change - en_US.ISO8859-1/htdocs/releases/11.0R/schedule.xml + en_US.ISO8859-1/htdocs/releases/12.0R/schedule.xml Change % beta.local.where IGNORE to INCLUDE share/xml/release.ent Update % betarel.vers to BETA1 share/xml/news.xml Add an entry announcing the BETA Once the &branch.relengx; branch is created, the various release-related documents need to be generated and manually added to the doc/ repository. Within release/doc, invoke &man.make.1; to generate errata.html, hardware.html, readme.html, and relnotes.html pages, which are then added to 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 must be set to on on the newly-added files before the pre-commit hooks will allow them to be added to the repository. Ports Changes During <literal>BETA</literal>, <literal>RC</literal>, and the Final <literal>RELEASE</literal> For each build during the release cycle, the MANIFEST files containing the SHA256 of the various distribution sets, such as base.txz, kernel.txz, and so on, are added to the misc/freebsd-release-manifests port. This allows utilities other than &man.bsdinstall.8;, such as ports-mgmt/poudriere, to safely use these distribution sets by providing a mechanism through which the checksums can be verified.