svn commit: r50119 - in head: en_US.ISO8859-1/articles en_US.ISO8859-1/articles/freebsd-releng en_US.ISO8859-1/articles/releng share/xml

Glen Barber gjb at FreeBSD.org
Fri Mar 31 22:36:29 UTC 2017


Author: gjb
Date: Fri Mar 31 22:36:27 2017
New Revision: 50119
URL: https://svnweb.freebsd.org/changeset/doc/50119

Log:
  Merge the ^/user/gjb/releng-rewrite branch to ^/head, which updates
  the Release Engineering process of the Project.
  
  Sponsored by:	The FreeBSD Foundation

Added:
  head/en_US.ISO8859-1/articles/freebsd-releng/
     - copied from r43296, user/gjb/releng-rewrite/en_US.ISO8859-1/articles/freebsd-releng/
  head/en_US.ISO8859-1/articles/freebsd-releng/Makefile
     - copied, changed from r43297, user/gjb/releng-rewrite/en_US.ISO8859-1/articles/freebsd-releng/Makefile
  head/en_US.ISO8859-1/articles/freebsd-releng/article.xml
     - copied, changed from r43297, user/gjb/releng-rewrite/en_US.ISO8859-1/articles/freebsd-releng/article.xml
  head/en_US.ISO8859-1/articles/freebsd-releng/extra.css
     - copied unchanged from r43297, user/gjb/releng-rewrite/en_US.ISO8859-1/articles/freebsd-releng/extra.css
  head/en_US.ISO8859-1/articles/freebsd-releng/releng-building.xml
     - copied, changed from r50079, user/gjb/releng-rewrite/en_US.ISO8859-1/articles/freebsd-releng/releng-building.xml
  head/en_US.ISO8859-1/articles/freebsd-releng/releng-major-version.xml
     - copied, changed from r49954, user/gjb/releng-rewrite/en_US.ISO8859-1/articles/freebsd-releng/releng-major-version.xml
  head/en_US.ISO8859-1/articles/freebsd-releng/releng-minor-version.xml
     - copied, changed from r49954, user/gjb/releng-rewrite/en_US.ISO8859-1/articles/freebsd-releng/releng-minor-version.xml
  head/en_US.ISO8859-1/articles/freebsd-releng/releng-mirrors.xml
     - copied, changed from r50081, user/gjb/releng-rewrite/en_US.ISO8859-1/articles/freebsd-releng/releng-mirrors.xml
  head/en_US.ISO8859-1/articles/freebsd-releng/releng-terminology.xml
     - copied, changed from r49954, user/gjb/releng-rewrite/en_US.ISO8859-1/articles/freebsd-releng/releng-terminology.xml
Modified:
  head/en_US.ISO8859-1/articles/Makefile
  head/en_US.ISO8859-1/articles/releng/article.xml
  head/share/xml/urls.ent
Directory Properties:
  head/en_US.ISO8859-1/   (props changed)
  head/share/   (props changed)

Modified: head/en_US.ISO8859-1/articles/Makefile
==============================================================================
--- head/en_US.ISO8859-1/articles/Makefile	Fri Mar 31 21:15:54 2017	(r50118)
+++ head/en_US.ISO8859-1/articles/Makefile	Fri Mar 31 22:36:27 2017	(r50119)
@@ -11,6 +11,7 @@ SUBDIR+= explaining-bsd
 SUBDIR+= filtering-bridges
 SUBDIR+= fonts
 SUBDIR+= freebsd-questions
+SUBDIR+= freebsd-releng
 SUBDIR+= freebsd-update-server
 SUBDIR+= geom-class
 SUBDIR+= gjournal-desktop

Copied and modified: head/en_US.ISO8859-1/articles/freebsd-releng/Makefile (from r43297, user/gjb/releng-rewrite/en_US.ISO8859-1/articles/freebsd-releng/Makefile)
==============================================================================
--- user/gjb/releng-rewrite/en_US.ISO8859-1/articles/freebsd-releng/Makefile	Sun Dec  8 08:02:51 2013	(r43297, copy source)
+++ head/en_US.ISO8859-1/articles/freebsd-releng/Makefile	Fri Mar 31 22:36:27 2017	(r50119)
@@ -3,19 +3,18 @@
 #
 # Article: FreeBSD Release Engineering
 
-DOC?= article
+DOC?=		article
 
-FORMATS?= html
-WITH_ARTICLE_TOC?= YES
+FORMATS?=	html html-split
 
-INSTALL_COMPRESSED?= gz
+INSTALL_COMPRESSED?=gz
 INSTALL_ONLY_COMPRESSED?=
 
 SRCS=		article.xml
 
-CSS_SHEET_ADDITIONS= extra.css
+CSS_SHEET_ADDITIONS=extra.css
 
 URL_RELPREFIX?=	../../../..
-DOC_PREFIX?= ${.CURDIR}/../../..
+DOC_PREFIX?=	${.CURDIR}/../../..
 
 .include "${DOC_PREFIX}/share/mk/doc.project.mk"

Copied and modified: head/en_US.ISO8859-1/articles/freebsd-releng/article.xml (from r43297, user/gjb/releng-rewrite/en_US.ISO8859-1/articles/freebsd-releng/article.xml)
==============================================================================
--- user/gjb/releng-rewrite/en_US.ISO8859-1/articles/freebsd-releng/article.xml	Sun Dec  8 08:02:51 2013	(r43297, copy source)
+++ head/en_US.ISO8859-1/articles/freebsd-releng/article.xml	Fri Mar 31 22:36:27 2017	(r50119)
@@ -3,14 +3,32 @@
 	"http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd" [
 
 <!-- local entities -->
+<!ENTITY team.doceng "&os; Documentation Engineering Team">
+<!ENTITY team.portmgr "&os; Ports Management Team">
+<!ENTITY team.postmaster "&os; Postmaster Team">
 <!ENTITY team.re "&os; Release Engineering Team">
 <!ENTITY team.secteam "&os; Security Team">
-<!ENTITY team.portmgr "&os; Ports Management Team">
-<!ENTITY team.doceng "&os; Documentation Engineering Team">
+<!ENTITY branch.head "<literal xmlns='http://docbook.org/ns/docbook'>head/</literal>">
+<!ENTITY branch.stable "<literal xmlns='http://docbook.org/ns/docbook'>stable/</literal>">
+<!ENTITY branch.stablex "<literal xmlns='http://docbook.org/ns/docbook'>stable/<replaceable>11</replaceable>/</literal>">
+<!ENTITY branch.releng "<literal xmlns='http://docbook.org/ns/docbook'>releng/</literal>">
+<!ENTITY branch.relengx "<literal xmlns='http://docbook.org/ns/docbook'>releng/<replaceable>11.0</replaceable>/</literal>">
+<!ENTITY branch.releasex "<literal xmlns='http://docbook.org/ns/docbook'>release/<replaceable>11.0.0</replaceable>/</literal>">
+<!ENTITY branch.revision "<replaceable xmlns='http://docbook.org/ns/docbook'>11.0</replaceable>">
+
+<!-- Externally included files -->
+<!ENTITY release.building SYSTEM "./releng-building.xml">
+<!ENTITY release.major.version SYSTEM "./releng-major-version.xml">
+<!ENTITY release.minor.version SYSTEM "./releng-minor-version.xml">
+<!ENTITY release.mirrors SYSTEM "./releng-mirrors.xml">
+<!ENTITY release.terminology SYSTEM "./releng-terminology.xml">
 ]>
-<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
+<article xmlns="http://docbook.org/ns/docbook"
+  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+  xml:lang="en">
 
-  <info><title>&os; Release Engineering</title>
+  <info>
+    <title>&os; Release Engineering</title>
 
     <legalnotice xml:id="trademarks" role="trademarks">
       &tm-attrib.freebsd;
@@ -32,30 +50,30 @@
 
     <para>Development of &os; has a very specific workflow.  In
       general, all changes to the &os; base system are committed to
-      the <literal>head/</literal> branch, which reflects the top of
-      the source tree.</para>
+      the &branch.head; branch, which reflects the top of the source
+      tree.</para>
 
     <para>After a reasonable testing period, changes can then be
-      merged to the <literal>stable/</literal> branches.  The default
-      minimum timeframe before merging to <literal>stable/</literal>
-      branches is three (3) days.</para>
+      merged to the &branch.stable; branches.  The default minimum
+      timeframe before merging to &branch.stable; branches is three
+      (3) days.</para>
 
     <para>Although a general rule to wait a minimum of three days
-      before mergeing from <literal>head/</literal>, 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.</para>
+      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.</para>
 
     <para>After several months, and the number of changes in the
-      <literal>stable/</literal> branch have grown significantly, it
-      is time to release the next version of &os;.  These releases
-      have been historically referred to as <quote>point</quote>
+      &branch.stable; branch have grown significantly, it is time to
+      release the next version of &os;.  These releases have been
+      historically referred to as <quote>point</quote>
       releases.</para>
 
-    <para>In between releases from the <literal>stable/</literal>
-      branches, approximately every two (2) years, a release will be
-      cut directly from <literal>head/</literal>.  These releases
-      have been historically referred to as <quote>dot-zero</quote>
+    <para>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 <quote>dot-zero</quote>
       releases.</para>
 
     <para>This article will highlight the workflow and
@@ -76,6 +94,16 @@
       </varlistentry>
 
       <varlistentry>
+	<term><xref linkend="releng-terms"/></term>
+
+	<listitem>
+	  <para>Terminology and general information, such as the
+	    <quote>code slush</quote> and <quote>code
+	      freeze</quote>, used throughout this document.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
 	<term><xref linkend="releng-head"/></term>
 
 	<listitem>
@@ -92,6 +120,31 @@
 	    <quote>point</quote> release.</para>
 	</listitem>
       </varlistentry>
+
+      <varlistentry>
+	<term><xref linkend="releng-building"/></term>
+
+	<listitem>
+	  <para>Information related to the specific procedures to
+	    build installation medium.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term><xref linkend="releng-mirrors"/></term>
+
+	<listitem>
+	  <para>Procedures to publish installation medium.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term><xref linkend="releng-wrapup"/></term>
+
+	<listitem>
+	  <para>Wrapping up the release cycle.</para>
+	</listitem>
+      </varlistentry>
     </variablelist>
   </sect1>
 
@@ -115,75 +168,248 @@
 
 	<tbody>
 	  <row>
-	    <entry><literal>head/</literal> slush:</entry>
-	    <entry>August 24</entry>
+	    <entry>&branch.head; slush:</entry>
+	    <entry>May 27, 2016</entry>
+	  </row>
+
+	  <row>
+	    <entry>&branch.head; freeze:</entry>
+	    <entry>June 10, 2016</entry>
 	  </row>
 
 	  <row>
-	    <entry><literal>head/</literal> freeze:</entry>
-	    <entry>September 7</entry>
+	    <entry>&branch.head; KBI freeze:</entry>
+	    <entry>June 24, 2016</entry>
 	  </row>
 
 	  <row>
-	    <entry><literal>head/</literal> KBI freeze:</entry>
-	    <entry>September 21</entry>
+	    <entry><literal>doc/</literal> tree slush [1]:</entry>
+	    <entry>June 24, 2016</entry>
 	  </row>
 
 	  <row>
-	    <entry><literal>stable/<replaceable>10</replaceable>/</literal>
-	      branch:</entry>
-	    <entry>October 10</entry>
+	    <entry>Ports quarterly branch [2]:</entry>
+	    <entry>July 1, 2016</entry>
+	  </row>
+
+	  <row>
+	    <entry>&branch.stablex; branch:</entry>
+	    <entry>July 8, 2016</entry>
+	  </row>
+
+	  <row>
+	    <entry><literal>doc/</literal> tree tag [3]:</entry>
+	    <entry>July 8, 2016</entry>
 	  </row>
 
 	  <row>
 	    <entry>BETA1 build starts:</entry>
-	    <entry>October 12</entry>
+	    <entry>July 8, 2016</entry>
+	  </row>
+
+	  <row>
+	    <entry>&branch.head; thaw:</entry>
+	    <entry>July 9, 2016</entry>
 	  </row>
 
 	  <row>
 	    <entry>BETA2 build starts:</entry>
-	    <entry>October 18</entry>
+	    <entry>July 15, 2016</entry>
+	  </row>
+
+	  <row>
+	    <entry>BETA3 build starts [*]:</entry>
+	    <entry>July 22, 2016</entry>
 	  </row>
 
 	  <row>
-	    <entry><literal>releng/<replaceable>10.0</replaceable>/</literal>
-	      branch:</entry>
-	    <entry>November 1</entry>
+	    <entry>&branch.relengx; branch:</entry>
+	    <entry>July 29, 2016</entry>
 	  </row>
 
 	  <row>
 	    <entry>RC1 build starts:</entry>
-	    <entry>November 1</entry>
+	    <entry>July 29, 2016</entry>
+	  </row>
+
+	  <row>
+	    <entry>&branch.stablex; thaw:</entry>
+	    <entry>July 30, 2016</entry>
 	  </row>
 
 	  <row>
 	    <entry>RC2 build starts:</entry>
-	    <entry>November 9</entry>
+	    <entry>August 5, 2016</entry>
+	  </row>
+
+	  <row>
+	    <entry>Final Ports package builds [4]:</entry>
+	    <entry>August 6, 2016</entry>
+	  </row>
+
+	  <row>
+	    <entry>Ports release tag:</entry>
+	    <entry>August 12, 2016</entry>
+	  </row>
+
+	  <row>
+	    <entry>RC3 build starts [*]:</entry>
+	    <entry>August 12, 2016</entry>
 	  </row>
 
 	  <row>
 	    <entry>RELEASE build starts:</entry>
-	    <entry>November 19</entry>
+	    <entry>August 19, 2016</entry>
+	  </row>
+
+	  <row>
+	    <entry>RELEASE announcement:</entry>
+	    <entry>September 2, 2016</entry>
 	  </row>
 	</tbody>
       </tgroup>
     </informaltable>
 
-    <para>After general agreement on the schedule, the &team.re;
-      emails the the schedule to the &os; Developers.</para>
-  </sect1>
-
-  <sect1 xml:id="releng-head">
-    <title>Release from <literal>head/</literal></title>
+    <note>
+      <para>Items marked with "[*]" are "as
+	needed".</para>
+    </note>
+
+    <orderedlist>
+      <listitem>
+	<para>The <literal>doc/</literal> tree slush is coordinated by
+	  the &team.doceng;.</para>
+      </listitem>
+
+      <listitem>
+	<para>The Ports quarterly branch used is determined by when
+	  the final <acronym>RC</acronym> 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;.</para>
+      </listitem>
+
+      <listitem>
+	<para>The <literal>doc/</literal> tree is tagged by the
+	  &team.doceng;.</para>
+      </listitem>
+
+      <listitem>
+	<para>The final Ports package build is done by the
+	  &team.portmgr; after the final (or what is expected to be
+	  final) <acronym>RC</acronym> build.</para>
+      </listitem>
+    </orderedlist>
+
+    <note>
+      <para>If the release is being created from an existing
+	&branch.stable; branch, the <acronym>KBI</acronym>
+	freeze date can be excluded, since the <acronym>KBI</acronym>
+	is already considered frozen on established
+	&branch.stable; branches.</para>
+    </note>
+
+    <para>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 <acronym>RC</acronym>.  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
+      <literal>RELEASE</literal> build.</para>
 
-    <para> </para>
+    <para>After general agreement on the schedule, the &team.re;
+      emails the schedule to the &os; Developers.</para>
 
+    <para>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 <quote>blanket approval</quote>
+      to a particular subset of the tree will be made.</para>
+
+    <para>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 <acronym>RC</acronym> builds.</para>
+
+    <para>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;.</para>
+
+    <para>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.</para>
+
+    <para>The schedule is also added to the Project website, in the
+      <literal>doc/</literal> repository, in
+      <filename>head/en_US.ISO8859-1/htdocs/releases/&branch.revision;R/schedule.xml</filename>.
+      This file is continuously updated as the release cycle
+      progresses.</para>
+
+    <note>
+      <para>In most cases, the <filename>schedule.xml</filename> can
+	be copied from a prior release and updated accordingly.</para>
+    </note>
+
+    <para>The schedule is also linked from
+      <filename>head/en_US.ISO8859-1/htdocs/releng/index.xml</filename>.</para>
+
+    <para>Approximately one month prior to the scheduled <quote>code
+	slush</quote>, the &team.re; sends a reminder email to the
+      &os; Developers.</para>
+
+    <para>Once the first builds of the release cycle are available,
+      update the <literal>beta.local.where</literal> entity in
+      <filename>head/en_US.ISO8859-1/htdocs/releases/&branch.revision;R/schedule.xml</filename>.
+      replacing <literal>IGNORE</literal> with
+      <literal>INCLUDE</literal>.</para>
+
+    <note>
+      <para>If two parallel release cycles are happening at once, the
+	<literal>beta2.local.where</literal> entity may be used
+	instead.</para>
+    </note>
   </sect1>
 
-  <sect1 xml:id="releng-stable">
-    <title>Release from <literal>stable/</literal></title>
-
-    <para> </para>
-
+  &release.terminology;
+  &release.major.version;
+  &release.minor.version;
+  &release.building;
+  &release.mirrors;
+
+  <sect1 xml:id="releng-wrapup">
+    <title>Wrapping up the Release Cycle</title>
+
+    <para>This section describes general post-release tasks.</para>
+
+    <sect2 xml:id="releng-wrapup-en">
+      <title>Post-Release Errata Notices</title>
+
+      <para>As the release cycle approaches conclusion, it is common
+	to have several <acronym>EN</acronym> (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 <acronym>EN</acronym>.</para>
+    </sect2>
+
+    <sect2 xml:id="releng-wrapup-handoff">
+      <title>Handoff to the &team.secteam;</title>
+
+      <para>Roughly two weeks following the release, the Release
+	Engineer updates <filename>svnadmin/conf/approvers</filename>
+	changing the approver column from <literal>re</literal> to
+	<literal>(so|security-officer)</literal> for the
+	&branch.relengx; branch.</para>
+    </sect2>
   </sect1>
+
 </article>

Copied: head/en_US.ISO8859-1/articles/freebsd-releng/extra.css (from r43297, user/gjb/releng-rewrite/en_US.ISO8859-1/articles/freebsd-releng/extra.css)
==============================================================================
--- /dev/null	00:00:00 1970	(empty, because file is newly added)
+++ head/en_US.ISO8859-1/articles/freebsd-releng/extra.css	Fri Mar 31 22:36:27 2017	(r50119, copy of r43297, user/gjb/releng-rewrite/en_US.ISO8859-1/articles/freebsd-releng/extra.css)
@@ -0,0 +1,7 @@
+/*
+ * $FreeBSD$
+ */
+
+DIV.TITLEPAGE {
+	text-align: center;
+}

Copied and modified: head/en_US.ISO8859-1/articles/freebsd-releng/releng-building.xml (from r50079, user/gjb/releng-rewrite/en_US.ISO8859-1/articles/freebsd-releng/releng-building.xml)
==============================================================================
--- user/gjb/releng-rewrite/en_US.ISO8859-1/articles/freebsd-releng/releng-building.xml	Thu Mar 23 20:32:21 2017	(r50079, copy source)
+++ head/en_US.ISO8859-1/articles/freebsd-releng/releng-building.xml	Fri Mar 31 22:36:27 2017	(r50119)
@@ -34,9 +34,34 @@
 	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.  See &man.release.7; and
+	each invocation.</para>
+
+      <para>As a brief example of using
+	<filename>src/release/release.sh</filename> to build a single
+	release in <filename
+	  class="directory">/scratch</filename>:</para>
+
+      <screen>&prompt.root; <userinput>/bin/sh /usr/src/release/release.sh</userinput></screen>
+
+      <para>As a brief example of using
+	<filename>src/release/release.sh</filename> to build a single,
+	cross-built release using a different target directory, create
+	a custom <filename>release.conf</filename> containing:</para>
+
+      <programlisting># release.sh configuration for powerpc/powerpc64
+CHROOTDIR="/scratch-powerpc64"
+TARGET="powerpc"
+TARGET_ARCH="powerpc64"
+KERNEL="GENERIC64"</programlisting>
+
+      <para>Then invoke <filename>src/release/release.sh</filename>
+	as:</para>
+
+      <screen>&prompt.root; <userinput>/bin/sh /usr/src/release/release.sh -c <replaceable>$HOME/release.conf</replaceable></userinput></screen>
+
+      <para>See &man.release.7; and
 	<filename>src/release/release.conf.sample</filename> for more
-	details.</para>
+	details and example usage.</para>
     </sect3>
 
     <sect3 xml:id="releng-build-scripts-multiple">
@@ -54,22 +79,169 @@
       <para>The wrapper script is called
 	<filename>thermite.sh</filename>, which is available in the
 	&os; Subversion repository at
-	<literal>svn://svn.freebsd.org/user/gjb/thermite/</literal>,
+	<literal>svn://svn.freebsd.org/base/user/gjb/thermite/</literal>,
 	in addition to configuration files used to build
 	&branch.head; and &branch.stablex; development
 	snapshots.</para>
+
+      <para>Using <filename>thermite.sh</filename> is covered in <xref
+	  linkend="releng-build-snapshot"/> and <xref
+	  linkend="releng-build-release"/>.</para>
+
+      <para>Each architecture and individual kernel have their own
+	configuration file used by <filename>release.sh</filename>.
+	Each branch has its own <filename>defaults-X.conf</filename>
+	configuration which contains entries common throughout each
+	architecture, where overrides or special variables are set
+	and/or overridden in the per-build files.</para>
+
+      <para>The per-build configuration file naming scheme is in the
+	form of
+	<filename>${revision}-${TARGET_ARCH}-${KERNCONF}-${type}.conf</filename>,
+	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.</para>
+
+      <para>Each branch also has its own
+	<filename>builds-X.conf</filename> configuration, which is
+	used by <filename>thermite.sh</filename>.  The
+	<filename>thermite.sh</filename> 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.</para>
+
+      <para>There are two paths of file sourcing:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para><filename>builds-<replaceable>11</replaceable>.conf</filename>
+	    -> <filename>main.conf</filename></para>
+	  <para>This controls <filename>thermite.sh</filename>
+	    behavior</para>
+	</listitem>
+
+	<listitem>
+	  <para><filename><replaceable>11</replaceable>-<replaceable>amd64</replaceable>-<replaceable>GENERIC</replaceable>-<replaceable>snap</replaceable>.conf</filename>
+	    ->
+	    <filename>defaults-<replaceable>11</replaceable>.conf</filename>
+	    -> <filename>main.conf</filename></para>
+	  <para>This controls <filename>release/release.sh</filename>
+	    behavior within the build &man.chroot.8;</para>
+	</listitem>
+      </itemizedlist>
+
+      <note>
+	<para>The
+	  <filename>builds-<replaceable>11</replaceable>.conf</filename>,
+	  <filename>defaults-<replaceable>11</replaceable>.conf</filename>,
+	  and <filename>main.conf</filename> configuration files exist
+	  to reduce repetition between the various per-build
+	  files.</para>
+      </note>
     </sect3>
   </sect2>
 
   <sect2 xml:id="releng-build-snapshot">
     <title>Building &os; Development Snapshots</title>
 
-    <para> </para>
+    <para>The official release build machines have a specific
+      filesystem layout, which using <acronym>ZFS</acronym>,
+      <filename>thermite.sh</filename> takes heavy advantage of with
+      clones and snapshots, ensuring a pristine build
+      environment.</para>
+
+    <para>The build scripts reside in <filename
+	class="directory">/releng/scripts-snapshot/scripts</filename>
+      or <filename
+	class="directory">/releng/scripts-release/scripts</filename>
+      respectfully, to avoid collisions between an
+      <acronym>RC</acronym> build from a releng branch versus
+      a <literal>STABLE</literal> snapshot from the respective stable
+      branch.</para>
+
+    <para>A separate dataset exists for the final build images,
+      <filename class="directory">/snap/ftp</filename>.  This
+      directory contains both snapshots and releases directories.
+      They are only used if the <literal>EVERYTHINGISFINE</literal>
+      variable is defined in <filename>main.conf</filename>.</para>
+
+    <note>
+      <para>The <literal>EVERYTHINGISFINE</literal> 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.</para>
+    </note>
+
+    <para>As <filename>thermite.sh</filename> iterates through the
+      master list of combinations and locates the per-build
+      configuration file, a <acronym>ZFS</acronym> dataset is created
+      under <filename class="directory">/releng</filename>, such as
+      <filename
+	class="directory">/releng/12-amd64-GENERIC-snap</filename>.
+      The <literal>src/</literal>, <literal>ports/</literal>, and
+      <literal>doc/</literal> trees are checked out to separate
+      <acronym>ZFS</acronym> datasets, such as <filename
+	class="directory">/releng/12-src-snap</filename>, which are
+      then cloned and mounted into the respective build datasets.
+      This is done to avoid checking out a given tree more than
+      once.</para>
+
+    <para>Assuming these filesystem paths,
+      <filename>thermite.sh</filename> would be invoked as:</para>
+
+    <screen>&prompt.root; <userinput>cd /releng/scripts-snapshot/scripts</userinput>
+&prompt.root; <userinput>./setrev.sh -b &branch.stablex;</userinput>
+&prompt.root; <userinput>./zfs-setup.sh -c ./builds-<replaceable>11</replaceable>.conf</userinput>
+&prompt.root; <userinput>./thermite.sh -c ./builds-<replaceable>11</replaceable>.conf</userinput></screen>
   </sect2>
 
   <sect2 xml:id="releng-build-release">
     <title>Building &os; Releases</title>
 
-    <para> </para>
+    <para>Similar to building &os; development snapshots,
+      <filename>thermite.sh</filename> would be invoked the same way.
+      The difference between development snapshots and release builds,
+      <literal>BETA</literal> and <acronym>RC</acronym>, included, is
+      that the &man.chroot.8; configuration files must be named with
+      <literal>release</literal> instead of <literal>snap</literal> as
+      the "type", as mentioned above.</para>
+
+    <para>In addition, the <literal>BUILDTYPE</literal> and
+      <literal>types</literal> must be changed from
+      <literal>snap</literal> to <literal>release</literal> in
+      <filename>defaults-<replaceable>11</replaceable>.conf</filename>
+      and
+      <filename>builds-<replaceable>11</replaceable>.conf</filename>,
+      respectively.</para>
+
+    <para>When building <literal>BETA</literal>,
+      <acronym>RC</acronym>, and the final <literal>RELEASE</literal>,
+      also statically set <literal>BUILDSVNREV</literal> to the
+      revision on the branch reflecting the name change,
+      <literal>BUILDDATE</literal> to the date the builds are started
+      in <literal>YYYYMMDD</literal> format.  If the
+      <literal>doc/</literal> and <literal>ports/</literal> trees have
+      been tagged, also set <literal>PORTBRANCH</literal> and
+      <literal>DOCBRANCH</literal> to the relevant tag path in the
+      Subversion repository, replacing <literal>HEAD</literal> with
+      the last changed revision.  Also set
+      <literal>releasesrc</literal> in
+      <filename>builds-<replaceable>11</replaceable>.conf</filename>
+      to the relevant branch, such as &branch.stablex; or
+      &branch.relengx;.</para>
+
+    <para>After building the final <literal>RELEASE</literal>, the
+      &branch.relengx; branch is tagged as &branch.releasex; using the
+      revision from which the <literal>RELEASE</literal> was built.
+      Similar to creating the &branch.stablex; and &branch.relengx;
+      branches, this is done with <command>svn cp</command>.  From the
+      repository root:</para>
+
+    <screen>&prompt.user; <userinput>svn cp ^/&branch.relengx;@r<replaceable>306420</replaceable> &branch.releasex;</userinput>
+&prompt.user; <userinput>svn commit &branch.releasex;</userinput></screen>
   </sect2>
 </sect1>

Copied and modified: head/en_US.ISO8859-1/articles/freebsd-releng/releng-major-version.xml (from r49954, user/gjb/releng-rewrite/en_US.ISO8859-1/articles/freebsd-releng/releng-major-version.xml)
==============================================================================
--- user/gjb/releng-rewrite/en_US.ISO8859-1/articles/freebsd-releng/releng-major-version.xml	Thu Feb  9 16:53:39 2017	(r49954, copy source)
+++ head/en_US.ISO8859-1/articles/freebsd-releng/releng-major-version.xml	Fri Mar 31 22:36:27 2017	(r50119)
@@ -4,80 +4,193 @@
 
      $FreeBSD$
 -->
-  <sect1 xml:id="releng-head">
-    <title>Release from &branch.head;</title>
+<sect1 xml:id="releng-head">
+  <title>Release from &branch.head;</title>
 
 
-    <para>This section describes the general procedures of the &os;
-      release cycle from the &branch.head; branch.</para>
+  <para>This section describes the general procedures of the &os;
+    release cycle from the &branch.head; branch.</para>
 
-    <sect2 xml:id="releng-head-builds-alpha">
-      <title>&os; <quote><literal>ALPHA</literal></quote>
-	Builds</title>
-
-      <para>Starting with the &os; 10.0-RELEASE cycle, the notion
-	of <quote><literal>ALPHA</literal></quote> builds was
-	introduced.  Unlike the <literal>BETA</literal> and
-	<literal>RC</literal> builds, <literal>ALPHA</literal>
-	builds are not included in the &os; Release schedule.</para>
-
-      <para>The idea behind <literal>ALPHA</literal> builds is to
-	provide regular &os;-provided builds before the creation of
-	the &branch.stable; branch.</para>
-
-      <para>&os; <literal>ALPHA</literal> snapshots should be built
-	approximately once a week.</para>
-
-      <para>For the first <literal>ALPHA</literal> build, the
-	<varname>BRANCH</varname> value in
-	<filename>sys/conf/newvers.sh</filename> needs to be changed
-	from <literal>CURRENT</literal> to <literal>ALPHA1</literal>.
-	For subsequent <literal>ALPHA</literal> builds, increment
-	each <literal>ALPHA<replaceable>N</replaceable></literal>
-	value by one.</para>
-
-      <para>See <xref linkend="releng-building"/> for information on
-	building the <literal>ALPHA</literal> images.</para>
-    </sect2>
-
-    <sect2 xml:id="releng-head-freeze-kbi">
-      <title>The <acronym>KBI</acronym>/<acronym>KPI</acronym>
-	Freeze</title>
-
-      <para> </para>
-    </sect2>
-
-    <sect2 xml:id="releng-head-branching">
-      <title>Creating the &branch.stablex; Branch</title>
-
-      <para>When creating the &branch.stable; branch, several changes
-	are required in both the new &branch.stable; branch and the
-	&branch.head; branch.</para>
-
-      <?ignore
-      <informaltable frame="none" pgwide="0">
-	<tgroup cols="2">
-	  <thead>
-	    <row>
-	      <entry>File to Edit</entry>
-	      <entry>What to Change</entry>
-	    </row>
-	  </thead>
-
-	  <tbody>
-	    <row>
-	      <entry> </entry>
-	      <entry> </entry>
-	    </row>
-	  </tbody>
-	</tgroup>
-      </informaltable>
-      ?>
-    </sect2>
-
-    <sect2 xml:id="releng-head-thaw">
-      <title>Code Thaw in &branch.head;</title>
-
-      <para> </para>
-    </sect2>
-  </sect1>
+  <sect2 xml:id="releng-head-builds-alpha">
+    <title>&os; <quote><literal>ALPHA</literal></quote> Builds</title>
+
+    <para>Starting with the &os; 10.0-RELEASE cycle, the notion
+      of <quote><literal>ALPHA</literal></quote> builds was
+      introduced.  Unlike the <literal>BETA</literal> and
+      <literal>RC</literal> builds, <literal>ALPHA</literal> builds
+      are not included in the &os; Release schedule.</para>
+
+    <para>The idea behind <literal>ALPHA</literal> builds is to
+      provide regular &os;-provided builds before the creation of the
+      &branch.stable; branch.</para>
+
+    <para>&os; <literal>ALPHA</literal> snapshots should be built
+      approximately once a week.</para>
+
+    <para>For the first <literal>ALPHA</literal> build, the
+      <varname>BRANCH</varname> value in
+      <filename>sys/conf/newvers.sh</filename> needs to be changed
+      from <literal>CURRENT</literal> to <literal>ALPHA1</literal>.
+      For subsequent <literal>ALPHA</literal> builds, increment each
+      <literal>ALPHA<replaceable>N</replaceable></literal> value by
+      one.</para>
+
+    <para>See <xref linkend="releng-building"/> for information on
+      building the <literal>ALPHA</literal> images.</para>
+  </sect2>
+
+  <sect2 xml:id="releng-head-branching">
+    <title>Creating the &branch.stablex; Branch</title>
+
+    <para>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:</para>
+
+    <screen>&prompt.user; <userinput>svn cp head &branch.stablex;</userinput></screen>
+
+    <para>Once the &branch.stablex; branch has been committed, make
+      the following edits:</para>
+
+    <informaltable frame="none" pgwide="0">
+      <tgroup cols="2">
+	<thead>
+	  <row>
+	    <entry>File to Edit</entry>
+	    <entry>What to Change</entry>
+	  </row>
+	</thead>
+
+	<tbody>
+	  <row>
+	    <entry><filename>stable/<replaceable>11</replaceable>/UPDATING</filename></entry>
+	    <entry>Update the &os; version, and remove the notice
+	      about <literal>WITNESS</literal></entry>
+	  </row>
+
+	  <row>
+	    <entry><filename>stable/<replaceable>11</replaceable>/contrib/jemalloc/include/jemalloc/jemalloc_FreeBSD.h</filename></entry>
+	    <entry><screen>#ifndef MALLOC_PRODUCTION
+#define MALLOC_PRODUCTION
+#endif</screen></entry>
+	  </row>
+
+	  <row>
+	    <entry><filename>stable/<replaceable>11</replaceable>/sys/*/conf/GENERIC*</filename></entry>
+	    <entry>Remove debugging support</entry>
+	  </row>
+
+	  <row>
+	    <entry><filename>stable/<replaceable>11</replaceable>/release/release.conf.sample</filename></entry>
+	    <entry>Update <varname>SRCBRANCH</varname></entry>
+	  </row>
+
+	  <row>
+	    <entry><filename>stable/<replaceable>11</replaceable>/sys/*/conf/GENERIC-NODEBUG</filename></entry>
+	    <entry>Remove these kernel configurations</entry>
+	  </row>
+
+	  <row>
+	    <entry><filename>stable/<replaceable>11</replaceable>/sys/conf/newvers.sh</filename></entry>
+	    <entry>Update the <varname>BRANCH</varname> value to
+	      reflect <literal>BETA1</literal></entry>
+	  </row>
+	</tbody>
+      </tgroup>
+    </informaltable>
+
+    <para>Then in the &branch.head; branch, which will now become
+      a new major version:</para>
+
+    <informaltable frame="none" pgwide="0">
+      <tgroup cols="2">
+	<thead>
+	  <row>
+	    <entry>File to Edit</entry>
+	    <entry>What to Change</entry>
+	  </row>
+	</thead>
+
+	<tbody>
+	  <row>
+	    <entry><filename>head/UPDATING</filename></entry>
+	    <entry>Update the &os; version</entry>
+	  </row>
+
+	  <row>
+	    <entry><filename>head/gnu/usr.bin/groff/tmac/mdoc.local.in</filename></entry>
+	    <entry>Add the new &os; version</entry>
+	  </row>
+
+	  <row>
+	    <entry><filename>head/sys/conf/newvers.sh</filename></entry>
+	    <entry>Update the <varname>BRANCH</varname> value to
+	      reflect <literal>CURRENT</literal>, and increment
+	      <literal>REVISION</literal></entry>
+	  </row>
+
+	  <row>
+	    <entry><filename>head/Makefile.inc1</filename></entry>
+	    <entry>Update <varname>TARGET_TRIPLE</varname></entry>
+	  </row>
+
+	  <row>
+	    <entry><filename>head/sys/sys/param.h</filename></entry>
+	    <entry>Update <literal>__FreeBSD_version</literal></entry>
+	  </row>
+
+	  <row>
+	    <entry><filename>head/contrib/llvm/tools/clang/lib/Basic/Targets.cpp</filename></entry>
+	    <entry>Update
+	      <literal>__FreeBSD_cc_version</literal></entry>
+	  </row>
+
+	  <row>
+	    <entry><filename>head/gnu/usr.bin/cc/cc_tools/freebsd-native.h</filename></entry>
+	    <entry>Update <literal>FBSD_MAJOR</literal> and
+	      <literal>FBSD_CC_VER</literal></entry>
+	  </row>
+
+	  <row>
+	    <entry><filename>head/contrib/gcc/config.gcc</filename></entry>
+	    <entry>Append the
+	      <literal>freebsd<version>.h</literal>
+	      section</entry>
+	  </row>
+
+	  <row>
+	    <entry><filename>head/release/Makefile</filename></entry>
+	    <entry>Remove the
+	      <literal>debug.witness.trace</literal> entries</entry>
+	  </row>
+
+	  <row>
+	    <entry><filename>head/release/doc/en_US.ISO8859-1/readme/article.xml</filename></entry>
+	    <entry>Replace &a.current; with &a.stable;</entry>
+	  </row>
+
+	  <?ignore
+
+	  <row>
+	    <entry><filename>head/release/doc/share/xml/release.ent</filename></entry>
+	    <entry></entry>
+	  </row>
+
+	  ?>
+
+	  <row>
+	    <entry><filename>head/lib/clang/clang.build.mk</filename></entry>
+	    <entry>Uncomment <literal>-DNDEBUG</literal></entry>
+	  </row>
+
+	  <row>
+	    <entry><filename>head/lib/clang/freebsd_cc_version.h</filename></entry>
+	    <entry>Update
+	      <literal>FREEBSD_CC_VERSION</literal></entry>
+	  </row>
+	</tbody>
+      </tgroup>
+    </informaltable>
+  </sect2>
+</sect1>

Copied and modified: head/en_US.ISO8859-1/articles/freebsd-releng/releng-minor-version.xml (from r49954, user/gjb/releng-rewrite/en_US.ISO8859-1/articles/freebsd-releng/releng-minor-version.xml)
==============================================================================
--- user/gjb/releng-rewrite/en_US.ISO8859-1/articles/freebsd-releng/releng-minor-version.xml	Thu Feb  9 16:53:39 2017	(r49954, copy source)
+++ head/en_US.ISO8859-1/articles/freebsd-releng/releng-minor-version.xml	Fri Mar 31 22:36:27 2017	(r50119)
@@ -10,27 +10,165 @@
   <para>This section describes the general procedures of the &os;
     release cycle from an extablished &branch.stable; branch.</para>
 
+  <sect2 xml:id="releng-stable-slush">
+    <title>&os; <literal>stable</literal> Branch Code Slush</title>
+
+    <para>In preparation for the code freeze on
+      a <literal>stable</literal> 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:</para>
+
+    <informaltable frame="none" pgwide="0">
+      <tgroup cols="2">
+	<thead>
+	  <row>
+	    <entry>File to Edit</entry>
+	    <entry>What to Change</entry>
+	  </row>
+	</thead>
+
+	<tbody>
+	  <row>
+	    <entry><filename>gnu/usr.bin/groff/tmac/mdoc.local.in</filename></entry>
+	    <entry>Add the new &os; version</entry>
+	  </row>
+
+	  <row>
+	    <entry><filename>sys/conf/newvers.sh</filename></entry>
+	    <entry>Update the <varname>BRANCH</varname> value to
+	      reflect <literal>PRERELEASE</literal></entry>
+	  </row>
+
+	  <row>
+	    <entry><filename>Makefile.inc1</filename></entry>
+	    <entry>Update <varname>TARGET_TRIPLE</varname></entry>
+	  </row>
+	</tbody>
+      </tgroup>
+    </informaltable>
+  </sect2>
+
   <sect2 xml:id="releng-stable-builds-beta">
     <title>&os; <literal>BETA</literal> Builds</title>
 
-    <para> </para>
+    <para>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
+      <filename>base/svnadmin/conf/approvers</filename> to include
+      a regular expression matching the &branch.stablex; branch for
+      the release:</para>
+

*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***


More information about the svn-doc-all mailing list