os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Move the release engineering howto to the doc tree, and convert it to

Browse source 
DocBook SGML.  This version includes additional content from my paper
that isn't in www/en/internal/releng.sgml.  That file will be removed
once this shows up on the website properly.

PR:		docs/32697
Suggested by:	bmah, nik, others
TeX to DocBook Conversion by: Hiten Pandya <hiten@uk.FreeBSD.org>
This commit is contained in:
Murray Stokely 2002-01-01 05:25:13 +00:00
parent ba75884c26
commit 14233a1499
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=11547
4 changed files with 1000 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

29
en_US.ISO8859-1/articles/releng/Makefile Normal file
View file

@ -0,0 +1,29 @@
#
# $FreeBSD$
#
# Article: FreeBSD Release Engineering
DOC?= article
FORMATS?= html
INSTALL_COMPRESSED?= gz
INSTALL_ONLY_COMPRESSED?= true
# SGML content
SRCS= article.sgml branches.ascii
# IMAGES
IMAGES= branches.eps
CLEANFILES+= branch.aux branch.log branch.dvi
DOC_PREFIX?= ${.CURDIR}/../../..
branch.dvi: branch.tex
${LATEX} branch.tex
branches.eps: branch.dvi
${DVIPS} -o ${.TARGET} -E branch.dvi
.include "${DOC_PREFIX}/share/mk/doc.project.mk"

870
en_US.ISO8859-1/articles/releng/article.sgml Normal file
View file

@ -0,0 +1,870 @@
<!--
The FreeBSD Documentation Project
-->
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
<!ENTITY branches.ascii SYSTEM "branches.ascii">
<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
%man;
]>
<article>
<title>FreeBSD Release Engineering</title>
<articleinfo>
<!-- This paper was presented at BSDCon Europe in Brighton, UK on
November 11, 2001 -->
<confgroup>
<confdates>November 2001</confdates>
<conftitle>BSDCon Europe</conftitle>
</confgroup>
<authorgroup>
<author>
<firstname>Murray</firstname>
<surname>Stokely</surname>
<authorblurb>
<para>I've been involved in the development of FreeBSD based products
since 1997 at Walnut Creek CDROM, BSDi, and now Wind River Systems.
FreeBSD 4.4 was the first official release of FreeBSD that I played
a significant part in.</para>
</authorblurb>
<affiliation>
<address><email>murray@FreeBSD.org</email>
<otheraddr><ulink
url="http://www.FreeBSD.org/~murray">http://www.FreeBSD.org/~murray</ulink></otheraddr>
</address>
</affiliation>
</author>
</authorgroup>
<pubdate>$FreeBSD$</pubdate>
<abstract>
<para>This paper describes the approach used by the FreeBSD
release engineering team to make production quality releases
of the FreeBSD Operating System. It details the methodology
used for the release of FreeBSD 4.4 and describes the tools
available for those interested in producing customized FreeBSD
releases for corporate rollouts or commercial
productization.</para>
</abstract>
</articleinfo>
<!-- Introduction -->
<sect1 id="introduction">
<title>Introduction</title>
<para>The development of FreeBSD is a very open process. FreeBSD is
comprised of contributions from thousands of people around the
world. The FreeBSD Project provides anonymous
<acronym>CVS</acronym>[1] access to the general public so that
others can have access to log messages, diffs (patches) between
development branches, and other productivity enhancements that
formal source code management provides. This has been a huge help
in attracting more talented developers to FreeBSD. However, I
think everyone would agree that chaos would soon manifest if write
access was opened up to everyone on the Internet. Therefore only
a <quote>select</quote> group of nearly 300 people are given write
access to the <acronym>CVS</acronym> repository. These
<emphasis>committers[6]</emphasis> are responsible for the bulk of
FreeBSD development. An elected <emphasis>core-team[7]</emphasis>
of very senior developers provides some level of direction over
the project.</para>
<para>The rapid race of <systemitem
class="osname">FreeBSD</systemitem> development leaves little time
for polishing the development system into production quality
release. To solve this dilemma, development continues on two
parallel tracks. The main development branch is the
<emphasis>HEAD</emphasis> or the trunk of our CVS tree, known as
<quote>FreeBSD-CURRENT</quote> or <quote>-CURRENT</quote> for
short.</para>
<para>A more stable branch is maintained, known as
<quote>FreeBSD-STABLE</quote> or <quote>-STABLE</quote> for short.
Both branches live in a master CVS repository in California and
are replicated via <application
class="software">CVSup</application>[2] to mirrors all over the
world. FreeBSD-CURRENT[8] is the <quote>bleeding-edge</quote> of
FreeBSD development where all new changes first enter the system.
FreeBSD-STABLE is the development branch from which major releases
are made. Changes go into this branch at a different pace, and
with general assumption that they have first been submitted to
FreeBSD-CURRENT and have been thoroughly tested by our user
community.</para>
<para>In the interim period between releases, nightly snapshots are
built automatically by the FreeBSD Project build machines and made
available for download from <systemitem
class="resource">ftp://stable.FreeBSD.org/</systemitem>. The
widespread availability of binary release snapshots, and the
tendency of our user community to keep up with -STABLE development
with CVSup and <quote><command>make</command>
<MakeTarget>world</MakeTarget></quote>[8] helps to keep
FreeBSD-STABLE in a very reliable condition even before the
quality assurance activities ramp up pending a major
release.</para>
<para>Bug reports and feature requests are continuously submitted by
users throughout the cycle. Problems reports are entered into our
<application class="software">GNATS</application>[9] database
through email, and the &man.send-pr.1 application, or via the web
interface provided at <systemitem
class="resource">http://www.FreeBSD.org/send-pr.html</systemitem>.
In addition to the multitude of different technical mailing lists
about FreeBSD, the FreeBSD quality-assurance mailing list
(freebsd-qa@FreeBSD.org) provides a forum for discussing the finer
points of <quote>release-polishing</quote>.</para>
<para>To service our most conservative users, individual release
branches were introduced with <emphasis>FreeBSD 4.3</emphasis>.
These release branches are created shortly before a final release
is made, and after the release goes out, only the most critical
security fixes and additions are merged into the release branch.
In addition to source updates via CVS, binary patchkits are
available to keep systems on the <emphasis>RELENG_4_3 </emphasis>
and <emphasis>RELENG_4_4</emphasis> branches updated.</para>
<para><link linkend="release-proc">Section 2</link> discusses the
different phases of the release engineering process leading up to
the actual system build and <link linkend="release-build">section
3</link> descibes the actual build process. <link
linkend="extensibility">Section 4</link> describes how the base
release may be extended by third parties and <link
linkend="lessons-learned">section 5</link> details some of the
lessons learned through the release of FreeBSD 4.4. Finally,
<link linkend="future">section 6</link> presents future directions
of development.</para>
</sect1>
<!-- Release Process -->
<sect1 id="release-proc">
<title>Release Process</title>
<para>New releases of FreeBSD are released from the -STABLE branch
at approximately four month intervals. The FreeBSD release
process begins to ramp up 45 days before the anticipated release
date when the release engineer send an email to the development
mailing lists to reming developers that they only have 15 days to
intergrate new changes before the code freeze. During this time,
many developers perform what have become know as <quote>MFC
sweeps</quote>. <acronym>MFC</acronym> stands for <quote>Merge
From CURRENT</quote> and it describes the process of merging a
tested change from our -CURRENT development branch to our -STABLE
branch.</para>
<sect2>
<title>Code Review</title>
<para>Thiry days before the anticipated release, the source
repository enters a <quote>code slush</quote>. During this
time, all commits to the -STABLE branch must be approved by the
release engineer (re@FreeBSD.org). The kinds of changes that
are allowed during this 15 day period include:</para>
<itemizedlist>
<listitem>
<para>Bug fixes.</para>
</listitem>
<listitem>
<para>Documentation updates.</para>
</listitem>
<listitem>
<para>Security-related fixes of any kind.</para>
</listitem>
<listitem>
<para>Minor changes to device drivers, such as adding new Device
IDs</para>
</listitem>
<listitem>
<para>Any additional change that the release engineering team feels
is justified, given the potential risk</para>
</listitem>
</itemizedlist>
<para>After the first 15 days of the code slush, a
<emphasis>release candidate</emphasis> is released for
widespread testing and the code enters a <quote>code
freeze</quote> where it becomes much harder to justify new
changes to the system unless a serious bug-fix or security issue
is involved. During the code freeze, at least one release
candidate is released per week, until the final release is
ready. During the days leading to the final release, the
release engineering team is in constant communication with the
security-officer team, the documentation maintainers, and the
port maintainers, in-order to make sure that all of the
different components required for a successful release are
available.</para>
</sect2>
<sect2>
<title>Final Release Checklist</title>
<para>When several release candidates have been made available for
widespread testing and all major issues have been resolved, the
final release <quote>polishing</quote> can begin.</para>
<sect3>
<title>Creating the Release Branch</title>
<para>As described in the introduction, the RELENG_X_Y release
branch is a relatively new addition to our release engineering
methodology. The first step in creating this branch is to
ensure that you arw working with the newest version of the
RELENG_X sources that you want to branch
<emphasis>from</emphasis>.</para>
<screen>/usr/src&prompt.root; <userinput>cvs up -rRELENG_4 -P -d</userinput></screen>
<para>The next step is to create a branch point
<emphasis>tag</emphasis>, so that diffs against the start of
the branch are easier with CVS :</para>
<screen>/usr/src&prompt.root; <userinput>cvs rtag -rRELENG_4 RELENG_4_4_BP src</userinput></screen>
<para>And then a new branch tag is created with : </para>
<screen>/usr/src&prompt.root; <userinput>cvs rtag -b -rRELENG_4_4_BP RELENG_4_4 src</userinput></screen>
<note>
<para><emphasis>Access to this commands is restricted to the
CVS-meisters and release engineers</emphasis></para>
</note>
<sidebar>
<para>A <quote><emphasis>tag</emphasis></quote> is a CVS
vernacular for a label that identifies the source at a specific point
in time. By tagging the tree, we ensure that future release builders
will always be able to use the same source we used to create the
official FreeBSD Project releases.</para>
</sidebar>
<mediaobject>
<imageobject>
<imagedata fileref="branches" align="center">
</imageobject>
<textobject>
<literallayout>
&branches.ascii;
</literallayout>
</textobject>
<textobject>
<phrase>FreeBSD Development Branches</phrase>
</textobject>
</mediaobject>
</sect3>
<sect3>
<title>Bumping up the Version Number</title>
<para>Before the final release can be tagged, built, and
released, the following files need to be modified to reflect
the correct version of FreeBSD : </para>
<itemizedlist>
<listitem>
<para><filename>src/sys/conf/newvers.sh</filename></para>
</listitem>
<listitem>
<para><filename>src/sys/sys/param.h</filename></para>
</listitem>
<listitem>
<para><filename>src/release/doc/share/sgml/release/ent</filename></para>
</listitem>
<listitem>
<para><filename>src/gnu/usr.bin/groff/tmac/mdoc.local</filename></para>
</listitem>
<listitem>
<para><filename>doc/share/sgml/freebsd.ent</filename></para>
</listitem>
<listitem>
<para><filename>doc/en_US.ISO8859-1/books/handbook/mirrors/chapter.sgml
</filename></para>
</listitem>
<listitem>
<para><filename>www/en/releases/*</filename></para>
</listitem>
<listitem>
<para><filename>src/UPDATING</filename></para>
</listitem>
</itemizedlist>
<para>The release notes and errata files also need to be adjusted for the
new release (on the release branch) and truncated appropriately
(on the stable/current branch):</para>
<itemizedlist>
<listitem>
<para><filename>src/release/doc/en_US.ISO8859-1/relnotes/common/new.sgml
</filename></para>
</listitem>
<listitem>
<para><filename>src/release/doc/en_US.ISO8859-1/errata/article.sgml
</filename></para>
</listitem>
</itemizedlist>
</sect3>
<sect3>
<title>Creating Release Tags</title>
<para>When the final release is ready, the following command
will create the <literal>RELENG_4_4_0_RELEASE</literal>
tag.</para>
<screen>
/usr/src&prompt.root; <userinput>cvs rtag -rRELENG_4_4 RELENG_4_4_0_RELEASE src</userinput>
</screen>
<para>The Documentation and Ports managers are responsible for
tagging the respective trees with the <literal>RELEASE_4_4_0</literal>
tag.</para>
<para>Occasionally, a lost minute fix may be required
<emphasis>after </emphasis> the final tags have been created.
In practice this isn't a problem, since <acronym>CVS</acronym>
allows tags to be manipulated with <command>cvs
<replaceable>tag -d tagname filename</replaceable> </command>.
It is very important that any last minute changes be tagged
appropriately as part of the release. FreeBSD releases must
always be reproduceable. Local hacks in the release
engineer's environment are not acceptable.</para>
</sect3>
</sect2>
</sect1>
<!-- Release Building -->
<sect1 id="release-build">
<title>Release Building</title>
<para>FreeBSD <quote>releases</quote> can be built by anyone with a
fast machine and access to a source repository. (That should be
everyone, since we offer anonymous CVS! See The Handbook for
details.). The <emphasis>only</emphasis> special requirement is
that the <devicename>vn</devicename> (<emphasis>On -CURRENT, this
device has been replaced by the new <devicename>md</devicename>
memory disk driver </emphasis>.) device must be available. If the
device is not loaded into your kernel, then the kernel module
should be automatically loaded when &man.vnconfig.8; is executed
during the boot media creation phase. All of the tools necessary
to build a release are available from the CVS repository in
<filename>src/release</filename>. These tools aim to provide a
consistent way to build FreeBSD releases. A complete release can
actually be built with only a single command, including the
creation of <acronym>ISO</acronym> images suitable for burning to
CDROM, installation floppies, and an FTP install directory. This
command is aptly named <quote><command>make
<literal>release</literal></command></quote>.</para>
<sect2>
<title><quote>make release</quote></title>
<para>To successfully build a release, you must first populate
<filename>/usr/obj</filename> by running <quote><command>make
<literal>world</literal></command></quote> or simply
<quote><command>make
<literal>buildworld</literal></command></quote>. The release
target requires several variables be set properly to build a
release :</para>
<itemizedlist>
<listitem>
<para><makevar>CHROOTDIR</makevar> - The directory to be used as the
chroot environment for the entire release build.</para>
</listitem>
<listitem>
<para><makevar>BUILDNAME</makevar> - The name of the release to be
built.</para>
</listitem>
<listitem>
<para><makevar>CVSROOT</makevar> - The location of a CVS Repository.
</para>
</listitem>
<listitem>
<para><makevar>RELEASETAG</makevar> - The CVS tag corresponding to the
release you would like to build.</para>
</listitem>
</itemizedlist>
<para>There are many other variables available to customize the
release build. Most of these variables are documented at the
top of <filename>src/release/Makefile</filename>. The exact
command used to build the official FreeBSD 4.4 (x86) release
was : </para>
<screen><command>make <literal>release CHROOTDIR=/local3/release \
BUILDNAME=4.4-RELEASE \
CVSROOT=/host/cvs/usr/home/ncvs \
RELEASETAG=RELENG_4_4_0_RELEASE</literal>
</command>
</screen>
<para>The release Makefile can be broken down into several distinct
steps.</para>
<itemizedlist>
<listitem>
<para>Creation of a sanitized system environment in a separate
directory hierarchy with <quote><command>make
<literal>installworld</literal></command></quote>.
</para>
</listitem>
<listitem>
<para>Checkout from CVS of a clean version of the system source,
documentation, and ports into the release build hierarchy.</para>
</listitem>
<listitem>
<para>Population of <filename>/etc</filename> and
<filename>/dev</filename> in the chrooted environment.</para>
</listitem>
<listitem>
<para>chroot into the release build hierarchy, to make it harder for
the outside environment to taint this build.</para>
</listitem>
<listitem>
<para><quote><command>make <literal>world</literal></command></quote>
in the chroot<emphasis>ed</emphasis> environment.</para>
</listitem>
<listitem>
<para>Build of Kerberos-related binaries.</para>
</listitem>
<listitem>
<para>Build <quote><filename>GENERIC</filename></quote> kernel.</para>
</listitem>
<listitem>
<para>Creation of a staging directory tree where the binary
distributions will be built and packaged.</para>
</listitem>
<listitem>
<para>Build and installation of the documentation toolchain needed to
convert the documentation source (SGML) into HTML, and text documents
that will accompany the release.</para>
</listitem>
<listitem>
<para>Build and installation of the actual documentation
(user manuals, tutorials, release notes, hardware compatibility lists,
etc...)</para>
</listitem>
<listitem>
<para>Build of the <quote>crunched</quote> binaries used for
installation floppies.</para>
</listitem>
<listitem>
<para>Package up distribution tarballs of the binaries and sources.
</para>
</listitem>
<listitem>
<para>Create the boot media and a <quote>fixit</quote> floppy.</para>
</listitem>
<listitem>
<para>Create FTP installation hierarchy.</para>
</listitem>
<listitem>
<para><emphasis>(optionally)</emphasis> Create ISO images for
CDROM/DVD media.</para>
</listitem>
</itemizedlist>
</sect2>
<sect2>
<title>Contributed Software (<quote>ports</quote>)</title>
<para>The <ulink url="http://www.freebsd.org/ports">FreeBSD Ports
collection</ulink> is a collection of over 6,000 third-party
software packages available for FreeBSD. The ports team
(portmgr@FreeBSD.org) responsible for maintaining a consistent
ports tree that can be used to create the binary packages that
accompany a given FreeBSD release.</para>
<sect3>
<title>The Ports Cluster</title>
<para>In order to provide a consistent set of third-party
packages for FreeBSD releases, every port is built in a
separate chroot environment, starting with an empty
<filename>/usr/local</filename> and
<filename>/usr/X11R6</filename>. The requisite dependencies
are installed as packages before the build proceeds. This
enforces <emphasis>consistency</emphasis> in the package build
process. By starting the package build in a pristine
environment, we can assure that the package metadata (such as
required dependencies) is accurate, and so we will never
generate packages that might work on some systems and not on
others depending on what software was previously
installed.</para>
<para>The <quote>Ports Cluster</quote> for the x86 architecture
currently consists of a master node (Dual Pentium III 733Mhz)
and 8 slave nodes (Pentium III 800Mhz) to do the actual
package builds. With this configuration, a complete package
build takes over 24 hours. These machines are co-located with
the other FreeBSD Project equipment at Yahoo's corner of
Exodus in Santa Clara, CA.</para>
<para>The <quote>Ports Cluster</quote> for the Alpha
architecture consists of 7 PWS 500A machines donated by Compaq
and also co-located with Yahoo's facilities.</para>
</sect3>
<sect3>
<title>The Package Split</title>
<para>For FreeBSD 4.4 over 4.1 gigabytes of packages were
created. This causes a problem for CDROM distributions
because we would like to ship as many packages as possible
without making the user insert another disc to satisfy
dependencies. The solution is to create
<quote>clusters</quote> of like packages with similar
dependencies onto specific discs. The package split is
performed by the <ulink
url="mailto:portmgr@FreeBSD.org">portmgr</ulink> team in
coordination with the wishes of the general user community
with respect to which packages get to appear on the first
CD.</para>
</sect3>
</sect2>
<sect2>
<title>Release ISOs <emphasis>(CDROM/DVD)</emphasis></title>
<para>Starting with FreeBSD 4.4, the FreeBSD Project decided to
release all four ISO images that were previously sold on the
<emphasis>BSDi/Wind River Systems</emphasis>
<quote>official</quote> CDROM distributions. Each of the four
discs must contain a <filename>README.TXT</filename> file that
explains the contents of the disc, a
<filename>CDROM.INF</filename> file that provides meta-data for
the disc so that &man.sysinstall.8; can validate and use the
contents, and a <filename>filename.txt</filename> file that
provides a manifest for the disc. This
<emphasis>manifest</emphasis> can be created with a simple
command :</para>
<screen>/stage/cdrom&prompt.root; <userinput>find . -type f | sed -e 's/\^.\///' | sort > filename.txt</userinput></screen>
<para>The specific requirements of each CD is outlined below.</para>
<sect3>
<title>Disc #1</title>
<para>The first disc is almost completely created by
<quote><command>make
<literal>release</literal></command></quote>. The only changes
that should be made to the disc1 directory are the addition of
a 'tools' directory, <application
class="software">XFree86</application>, and as many popular
third party software packages as will fit on the disc. The
'tools' directory contains software that allow users to create
installation floppies from other operating systems. This disc
should be made bootable so that users of modern PCs do not
need to create installation floppy disks.</para>
<para>If an alternate version of XFree86 is to be provided, then
&man.sysinstall.8; must be updated to reflect the new location
and installation instructions. The relevant code is contained
in <filename>src/release/sysinstall</filename> on -STABLE or
<filename>src/usr.sbin/sysinstall</filename> on
-CURRENT. Specifically, the files <filename>dist.c</filename>,
<filename>menus.c</filename>, and
<filename>config.c</filename> will need to be updated.</para>
</sect3>
<sect3>
<title>Disc #2</title>
<para>The second disc is also largely created by <quote>make
release</quote>. This disc contains a <quote>live
filesystem</quote> that can be used from &man.sysinstall.8; to
troubleshoot a FreeBSD installation. This disc should be
bootable and should also contain a compressed copy of the CVS
repository in the <filename>CVSROOT</filename> directory and
commercial software demos in the <filename>commerce</filename>
directory.</para>
</sect3>
<sect3>
<title>Discs #3 and #4</title>
<para>The remaining two discs contains additional software
packages for FreeBSD. The packages should be clustered so that
a package and all of its <emphasis>dependencies</emphasis> are
included on the same disc.
</para>
</sect3>
</sect2>
</sect1>
<!-- Extensibility -->
<sect1 id="extensibility">
<title>Extensibility</title>
<para>Although FreeBSD forms a complete operating system, there is
nothing that forces you to use the system exactly as we have
packaged it up for distribution. We have tried to design the
system to be as extensible as possible so that it can serve as a
platform that other commercial products can be built on top
of. The only <quote>rule</quote> we have about this is that if you
are going to distribute FreeBSD with non-trivial changes, we
encourage you to document your enhancements! The FreeBSD community
can only help support users of the software we provide. We
certainly encourage innovation in the form of advanced
installation and administration tools, for example, but we can't
be expected to answer questions about it.</para>
<sect2>
<title>Creating Customized Boot floppies</title>
<para>Many sites have complex requirements that may require
additional kernel modules or userland tools be added to the
installation floppies. The <quote>quick and dirty</quote> way
to accomplish this would be to modify the staging directory of
an existing <quote>make release</quote> build hierarchy :</para>
<itemizedlist>
<listitem>
<para>Apply patches or add additional files inside the chroot
release build directory.</para>
</listitem>
<listitem>
<para><command>rm
<literal>${CHROOTDIR}/usr/obj/usr/src/\release/release.[48]</literal>
</command></para>
</listitem>
<listitem>
<para>rebuild &man.sysinstall.8;, the kernel, or whatever
parts of the system your change affected.</para>
</listitem>
<listitem>
<para><command>chroot <literal>${CHROOTDIR} ./mk release.4</literal>
</command></para>
</listitem>
<listitem>
<para><command>chroot <literal>${CHROOTDIR} ./mk release.8</literal>
</command></para>
</listitem>
</itemizedlist>
<para>New release floppies will be located in
<filename>${CHROOTDIR}/R/ stage/floppies</filename>.</para>
<para>Alternatively, the
<quote><filename>boot.flp</filename></quote> make
<emphasis>target</emphasis> can be called or the filesystem
creating script,
<filename>src/release/scripts/doFS.sh</filename> may be invoked
directly.</para>
<para>Local patches may also be supplied to the release build by
defining <makevar>LOCAL_PATCH</makevar> variable in <quote>make
release</quote>.
</para>
</sect2>
<sect2>
<title>Scripting <command>sysinstall</command></title>
<para>The FreeBSD system installation and configuration tool,
&man.sysinstall.8, can be scripted to provide automated installs
for large sites. This functionality can be used in conjunction
with Intel's PXE[13] to bootstrap systems from the network, or
via custom boot floppies with a sysinstall script. An example
sysinstall script is available in the CVS tree as
<filename>src/release/sysinstall/install.cfg</filename>.</para>
</sect2>
</sect1>
<!-- Lessons Learned -->
<sect1 id="lessons-learned">
<title>Lessons Learned from FreeBSD 4.4</title>
<para>The release engineering process for 4.4 formally began on
August 1st, 2001. After that date all commits to the
<literal>RELENG_4</literal> branch of FreeBSD had to be explicitly
approved by <ulink
url="mailto:re@FreeBSD.org">re@FreeBSD.org</ulink>. The first
release candidate for the x86 architecture was release on August
16, followed by 4 more release candidates leading up to the final
release on September 18th. The security officer was very involved
in the last week of the process as several security issues were
found in the earlier release candidates. A total of over
<emphasis>500</emphasis> emails were sent to re@FreeBSD.org in
little over a month.</para>
<para>Our user community has made it very clear that the security
and stability of a FreeBSD release should not be sacrificed for
any self-imposed deadlines or target release dates. The FreeBSD
Project has grown tremendously over its lifetime and the need for
standardized release engineering procedures has never been more
apparent. This will become even more important as FreeBSD is
ported to new platforms.</para>
</sect1>
<!-- Future Directions -->
<sect1 id="future">
<title>Future Directions</title>
<para>It is imperative for our release engineering activities to
scale with our growing userbase. Along these lines we are working
very hard to document the procedures involved in producing FreeBSD
releases.</para>
<itemizedlist>
<listitem>
<para><emphasis>Parallelism</emphasis> - Certain portions of the
release build are actually <quote>embarrasingly
parallel</quote>. Most of the tasks are very I/O intensive,
so multiple high-speed disk drives is actually important that
multiple processors in speeding up the <quote>make
release</quote> process. if multiple disks are used for
different hierarchies in the <emphasis>chroot</emphasis>
environment, then the CVS checkout of the ports and doc trees
can be happening simulatneously to the <quote>make
<literal>world</literal></quote> on another disk. Using a
<acronym>RAID</acronym> solution (hardware and software) can
significantly decrease overall build time.</para>
</listitem>
<listitem>
<para><emphasis>Cross-building releases</emphasis> - Building
IA-64 or Alpha release on x86 hardware? <quote>make
TARGET=ia64 release</quote>.
</para>
</listitem>
<listitem>
<para><emphasis>Regression Testing</emphasis> - We need better
automated correctness testing for FreeBSD.</para>
</listitem>
<listitem>
<para><emphasis>Installation Tools</emphasis> - Our installation
program has long since outlived its intended life span.
Several projects are under development to provide a more
advanced installation mechanism. One of the most promising is
the libh project[5] which aims to provided an intelligent new
package framework and GUI installation program.</para>
</listitem>
</itemizedlist>
</sect1>
<!-- Acknowledgments -->
<sect1 id="ackno">
<title>Acknowledgements</title>
<para>I would like to thank Jordan Hubbard for giving me the
opportunity to take some on some of the release engineering
responsibilities for FreeBSD 4.4 and also for all of his work
throughout the years making FreeBSD what it is today. Of course
the release wouldn't have been possible without all of the
release-related work done by <ulink
url="mailto:asami@FreeBSD.org">Satoshi Asami</ulink>, <ulink
url="mailto:steve@FreeBSD.org">Steve Price</ulink>, <ulink
url="mailto:bmah@FreeBSD.org">Bruce Mah</ulink>, <ulink
url="mailto:nik@FreeBSD.org">Nik Clayton</ulink>, <ulink
url="mailto:obrien@FreeBSD.org">David O'Brien</ulink>, <ulink
url="mailto:kris@FreeBSD.org">Kris Kennaway</ulink>, <ulink
url="mailto:jhb@FreeBSD.org">John Baldwin</ulink>, and the rest of
the FreeBSD development community. I would also like to thank
<ulink url="mailto:rgrimes@FreeBSD.org">Rod Grimes</ulink>, <ulink
url="mailto:phk@FreeBSD.org">Poul-Henning Kamp</ulink>, and others
who worked on the release engineering tools in the very early days
of FreeBSD. This article was influenced by release engineering
documents from the CSRG[14] , the NetBSD Project[11], and John
Baldwin's proposed release engineering process notes[12].</para>
</sect1>
<!-- Reference / Biblio Section -->
<sect1 id="biblio">
<title>References</title>
<para>[1] CVS - Concurrent Versions System <systemitem class="resource">
http://www.cvshome.org</systemitem></para>
<para>[2] CVSup - The CVS-Optimized General Purpose Network File Distribution
System <systemitem class="resource">http://www.polstra.com/projects/freeware/
CVSup</systemitem></para>
<para>[3] <systemitem class="resource">http://bento.FreeBSD.org</systemitem>
</para>
<para>[4] FreeBSD Ports Collection <systemitem class="resource">http://www.
FreeBSD.org/ports/</systemitem></para>
<para>[5] The libh Project
<systemitem class="resource">http://www.FreeBSD.org/projects/libh.html
</systemitem></para>
<para>[6] FreeBSD Committers
<systemitem class="resource">http://www.FreeBSD.org/doc/en_US.ISO8859-1/
articles/contributors/staff-committers.html</systemitem></para>
<para>[7] FreeBSD Core-Team
<systemitem class="resource">http://www.FreeBSD.org/doc/en_US.ISO8859-1/
articles/contibutors/staff-core.html</systemitem></para>
<para>[8] FreeBSD Handbook
<systemitem class="resource">http://www.FreeBSD.org/handbook</systemitem>
</para>
<para>[9] GNATS : The GNU Bug Tracking System
<systemitem class="resource">http://www.gnu.org/software/gnats/</systemitem>
</para>
<para>[10] FreeBSD PR Statistics
<systemitem class="resource">http://www.freebsd.org/prstats/index.html
</systemitem></para>
<para>[11] NetBSD Developer Documentation: Release Engineering
<systemitem class="resource">http://www.NetBSD.org/developers/releng/
index.html</systemitem></para>
<para>[12] John Baldwin's FreeBSD Release Engineering Proposal
<systemitem class="resource">http://people.FreeBSD.org/~jhb/docs/releng.txt
</systemitem></para>
<para>[13] PXE Jumpstart Guide
<systemitem class="resource">http://www.FreeBSD.org/doc/en_Us.ISO8859-1/
articles/pxe/index.html</systemitem></para>
<para>[14] Marshall Kirk McKusick, Michael J. Karels, and Keith Bostic
<emphasis>The Release Engineering of 4.3BSD</emphasis></para>
</sect1>
</article>

71
en_US.ISO8859-1/articles/releng/branch.tex Normal file
View file

@ -0,0 +1,71 @@
% $FreeBSD$
%
\documentclass{article}
\usepackage{epsfig}
\pagestyle{empty}
\begin{document}
\begin{figure*}
\caption{FreeBSD Development Branches}
\setlength{\unitlength}{1cm}
% define x, y dimensions in units so 10cm x 10cm
\begin{picture}(15, 8.5)
\footnotesize
% Ovals for the HEAD branch points.
\put(.75, .5){\dashbox{0.2}(2.5, 1)}
\put(2, 2.5){\oval(2.5, 1)}
\put(.75, 3.5){\dashbox{0.2}(2.5, 1)}
\put(2, 5.5){\oval(2.5, 1)}
\put(.75, 6.5){\framebox(2.5, 1){3.0-RELEASE}}
\put(2, 8){\vector(0,-1){.5}}
% Label the HEAD branch
\put(0, 4){\tt \shortstack{H\\E\\A\\D}}
%\multiput(2,1)(0, 1.5){5}{\oval(2.5, 1)}
% Labels for the HEAD branch points.
\put(1,1){\parbox{2.5cm}{5.0-CURRENT}}
\put(1,2.5){\parbox{2.5cm}{4.0-RELEASE}}
\put(1,4){4.0-CURRENT}
\put(1,5.5){3.1-RELEASE}
% Boxes for the 3.x releases
\put(3.75, 5.0){\framebox(1.25,1){3.2R}}
\put(5.5, 5.0){\framebox(1.25,1){3.3R}}
\put(7.25, 5.0){\framebox(1.25,1){3.4R}}
\put(9, 5.0){\framebox(1.25,1){3.5R}}
\put(10.75, 5.0){\framebox(1.25,1){3.5.1R}}
\put(12.5, 5.0){\dashbox{0.2}(2,1){3.x-STABLE}}
% Lines to connect the 3.x releases.
\multiput(3.25,5.5)(1.75,0){6}{\vector(1,0){.5}}
% Boxes for the 4.x releases
\put(3.75, 2.0){\framebox(1.25,1){4.1R}}
\put(5.5, 2.0){\framebox(1.25,1){4.1.1R}}
\put(7.25, 2.0){\framebox(1.25,1){4.2R}}
\put(9, 2.0){\framebox(1.25,1){4.3R}}
\put(10.75, 2.0){\framebox(1.25,1){4.4R}}
\put(12.5, 2.0){\dashbox{0.2}(2,1){4.x-STABLE}}
% Lines to connect the 4.x releases.
\multiput(3.25,2.5)(1.75,0){6}{\vector(1,0){.5}}
% Lines to connect the HEAD branch points.
\multiput(2,2)(0, 1.5){4}{\vector(0,-1){.5}}
% RELENG_4_[34] branches
\put(8.75, .5){\dashbox{0.2}(1.5, 1){\tt RELENG\_4\_3}}
\put(10.75, .5){\dashbox{0.2}(1.5, 1){\tt RELENG\_4\_4}}
% Lines to those branches
\put(9.75, 2){\vector(0,-1){.5}}
\put(11.25, 2){\vector(0,-1){.5}}
%\put(
%and RELENG_4_4Lines about RELENG_4_3 and RELENG_4_4
%% Now add some general labels
\put(8,6.5){\tt RELENG\_3}
\put(8,3.5){\tt RELENG\_4}
\end{picture}
\end{figure*}
\end{document}

30
en_US.ISO8859-1/articles/releng/branches.ascii Normal file
View file

@ -0,0 +1,30 @@
$FreeBSD$
| FreeBSD Development Branches
+--------------+
| 3.0-RELEASE |
| |
+--------------+
| RELENG_3
H ______|____ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ + - - - - - - +
E / \ | | | | | | | | | | | |
A |3.1-RELEASE|-|3.2R |-|3.3R |-|3.4R |-|3.5R |-| 3.5.1R|---| 3.x-STABLE |
D \___________/ |_ _ _| |_ _ _| |_ _ _| |_ _ _| |_ _ _ _| | |
| + - - - - - - +
|
+ - - - - - - - +
| 4.0-CURRENT |
| |
+ - - - - - - - +
| RELENG_4
_____|_____ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ + - - - - - - +
/ \ | | | | | | | | | | | |
|4.0-RELEASE|-|4.1R |-|4.1.1R |-|4.2R |-|4.3R |-|4.4R |---| 4.x-STABLE |
\___________/ |_ _ _| |_ _ _ _| |_ _ _| |_ _ _| |_ _ _| | |
| ___| |__ + - - - - - - +
| _ _ _ | _ _ _ _ _ |_ _ _ __
| | | | |
+ - - - - - - - + | RELENG_4_3 | | RELENG_4_4 |
| 5.0-CURRENT | |_ _ _ _ _ _ _| |_ _ _ _ _ _ _|
| |
+ - - - - - - - +