<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd" [
<!-- local entities -->
<!ENTITY team.bugmeister "&os; Bugmeister Team">
<!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 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>12</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>12.0</replaceable>/</literal>">
<!ENTITY branch.releasex "<literal xmlns='http://docbook.org/ns/docbook'>release/<replaceable>12.0.0</replaceable>/</literal>">
<!ENTITY branch.revision "<replaceable xmlns='http://docbook.org/ns/docbook'>12.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">
<!ENTITY release.website SYSTEM "./releng-website.xml">
]>
<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>
<authorgroup>
<author>
<personname>
<firstname>Glen</firstname>
<surname>Barber</surname>
</personname>
<affiliation>
<orgname class="nonprofit"> <link
xlink:href="https://www.freebsdfoundation.org">The
&os; Foundation</link></orgname>
</affiliation>
<affiliation>
<orgname> <link
xlink:href="https://www.netgate.com">Rubicon
Communications, LLC (Netgate)</link></orgname>
<address><email>gjb@FreeBSD.org</email></address>
</affiliation>
</author>
</authorgroup>
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.intel;
&tm-attrib.general;
</legalnotice>
<pubdate>$FreeBSD$</pubdate>
<abstract>
<para>This article describes the release engineering process of
the &os; Project.</para>
</abstract>
</info>
<sect1 xml:id="introduction">
<title>Introduction to the &os; Release Engineering
Process</title>
<para>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.</para>
<para>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.</para>
<para>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.</para>
<para>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 <quote>point</quote>
releases.</para>
<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
responsibilities of the &team.re; for both
<quote>dot-zero</quote> and <quote>point</quote>'
releases.</para>
<para>The following sections of this article describe:</para>
<variablelist>
<varlistentry>
<term><xref linkend="releng-prep"/></term>
<listitem>
<para>General information and preparation before
starting the release cycle.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><xref linkend="releng-website"/></term>
<listitem>
<para>Website Changes During the Release Cycle</para>
</listitem>
</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>
<para>The Release Engineering process for a
<quote>dot-zero</quote> release.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><xref linkend="releng-stable"/></term>
<listitem>
<para>The Release Engineering process for a
<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>
<sect1 xml:id="releng-prep">
<title>General Information and Preparation</title>
<para>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:</para>
<informaltable frame="none" pgwide="0">
<tgroup cols="2">
<thead>
<row>
<entry>Milestone</entry>
<entry>Anticipated Date</entry>
</row>
</thead>
<tbody>
<row>
<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>&branch.head; KBI freeze:</entry>
<entry>June 24, 2016</entry>
</row>
<row>
<entry><literal>doc/</literal> tree slush [1]:</entry>
<entry>June 24, 2016</entry>
</row>
<row>
<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>July 8, 2016</entry>
</row>
<row>
<entry>&branch.head; thaw:</entry>
<entry>July 9, 2016</entry>
</row>
<row>
<entry>BETA2 build starts:</entry>
<entry>July 15, 2016</entry>
</row>
<row>
<entry>BETA3 build starts [*]:</entry>
<entry>July 22, 2016</entry>
</row>
<row>
<entry>&branch.relengx; branch:</entry>
<entry>July 29, 2016</entry>
</row>
<row>
<entry>RC1 build starts:</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>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>August 19, 2016</entry>
</row>
<row>
<entry>RELEASE announcement:</entry>
<entry>September 2, 2016</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<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 <literal>RC</literal> 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) <literal>RC</literal> 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 <literal>RC</literal>. 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>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 <literal>RC</literal> builds.</para>
<note>
<para>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 <filename
class="directory">release/doc/</filename> to all &team.re;
members until the final <literal>RC</literal> to update the
release notes and other release-related documentation.</para>
</note>
<note>
<para>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.</para>
</note>
<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>In addition to adding <filename>schedule.xml</filename> to
the website, <filename>head/share/xml/navibar.ent</filename> and
<filename>head/share/xml/release.ent</filename> 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.</para>
<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>
&release.terminology;
&release.website;
&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>
<note>
<para>The actual process of issuing <acronym>EN</acronym>s is
handled by the &team.secteam;.</para>
</note>
<para>To request an Errata Notice after a release cycle has
completed, a developer should fill out the <link
xlink:href="https://www.freebsd.org/security/errata-template.txt">Errata
Notice template</link>, in particular the
<literal>Background</literal>, <literal>Problem
Description</literal>, <literal>Impact</literal>, and if
applicable, <literal>Workaround</literal> sections.</para>
<para>The completed Errata Notice template should be emailed
together with either a patch against the &branch.releng;
branch or a list of revisions from the &branch.stable;
branch.</para>
<para>For Errata Notice requests immediately following the
release, the request should be emailed to both the &team.re; and
the &team.secteam;. Once the &branch.releng; branch has been
handed over to the &team.secteam; as described in <xref
linkend="releng-wrapup-handoff"/>, Errata Notice requests
should be sent to the &team.secteam;.</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>
<sect1 xml:id="releng-eol">
<title>Release End-of-Life</title>
<para>This section describes the website-related files to update
when a release reaches <acronym>EoL</acronym>
(End-of-Life).</para>
<sect2 xml:id="releng-eol-website">
<title>Website Updates for End-of-Life</title>
<para>When a release reaches End-of-Life, references to that
release should be removed and/or updated on the
website:</para>
<informaltable frame="none" pgwide="0">
<tgroup cols="2">
<thead>
<row>
<entry>File</entry>
<entry>What to Change</entry>
</row>
</thead>
<tbody>
<row>
<entry><filename>head/en_US.ISO8859-1/htdocs/index.xsl</filename></entry>
<entry>Remove <literal>&u.relXXX.announce;</literal>
and <literal>&u.relXXX.current;</literal>
references.</entry>
</row>
<row>
<entry><filename>head/en_US.ISO8859-1/htdocs/releases/index.xml</filename></entry>
<entry>Move the &u.relXXX.*; macros from the
supported release list to the Legacy Releases
list.</entry>
</row>
<row>
<entry><filename>head/en_US.ISO8859-1/htdocs/releng/index.xml</filename></entry>
<entry>Update the appropriate releng branch to refelect
the branch is no longer supported.</entry>
</row>
<row>
<entry><filename>head/en_US.ISO8859-1/htdocs/security/security.xml</filename></entry>
<entry>Remove the branch from the supported branch
list.</entry>
</row>
<row>
<entry><filename>head/en_US.ISO8859-1/htdocs/where.xml</filename></entry>
<entry>Remove the URLs for the release.</entry>
</row>
<row>
<entry><filename>head/share/xml/navibar.ent</filename></entry>
<entry>Remove <literal>&u.relXXX.announce;</literal>
and <literal>&u.relXXX.current;</literal>
references.</entry>
</row>
<row>
<entry><filename>head/en_US.ISO8859-1/htdocs/security/advisory-template.txt</filename></entry>
<entry>Remove references to the release and releng
branch.</entry>
</row>
<row>
<entry><filename>head/en_US.ISO8859-1/htdocs/security/errata-template.txt</filename></entry>
<entry>Remove references to the release and releng
branch.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect2>
</sect1>
</article>
