path: root/en_US.ISO8859-1/articles/freebsd-releng/article.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;&nbsp;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;&nbsp;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 &quot;[*]&quot; are &quot;as
	needed&quot;.</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>&amp;u.relXXX.announce;</literal>
		and <literal>&amp;u.relXXX.current;</literal>
		references.</entry>
	    </row>

	    <row>
	      <entry><filename>head/en_US.ISO8859-1/htdocs/releases/index.xml</filename></entry>
	      <entry>Move the &amp;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>&amp;u.relXXX.announce;</literal>
		and <literal>&amp;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>