576 lines
19 KiB
XML
576 lines
19 KiB
XML
<?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>
|