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

* Fix tens of typos that were introduced in the TeX -> DocBook

Browse source 
conversion (how?)

* Remove the small section on package-building/splitting, and point to
  the seperate article that now covers this topic.
This commit is contained in:
Murray Stokely 2002-02-25 14:46:14 +00:00
parent 7617961f07
commit c38ceed60f
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=12286
1 changed files with 61 additions and 98 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -6,6 +6,9 @@
<!ENTITY branches.ascii SYSTEM "branches.ascii">
<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
%man;
<!ENTITY % freebsd PUBLIC "-//FreeBSD//ENTITIES DocBook Miscellaneous FreeBSD Entities//EN">
%freebsd;
<!ENTITY art.re.pkgs '<ulink url="../releng-packages/article.html">The Release Engineering of Third Party Packages</ulink>'>
]>
<article>
@ -72,14 +75,14 @@
of very senior developers provides some level of direction over
the project.</para>
<para>The rapid race of <systemitem
<para>The rapid pace of <systemitem
class="osname">FreeBSD</systemitem> development leaves little time
for polishing the development system into production quality
for polishing the development system into a 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>
<emphasis>HEAD</emphasis> or <emphasis>trunk</emphasis> 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.
@ -90,7 +93,7 @@
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
with general assumption that they have first gone into
FreeBSD-CURRENT and have been thoroughly tested by our user
community.</para>
@ -107,21 +110,21 @@
release.</para>
<para>Bug reports and feature requests are continuously submitted by
users throughout the cycle. Problems reports are entered into our
users throughout the release 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>.
through email, the &man.send-pr.1 application, or via the web
interface provided at <ulink
url="http://www.FreeBSD.org/send-pr.html"></ulink>
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>.
branches were introduced with FreeBSD 4.3.
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.
is made. After the release goes out, only the most critical
security fixes and additions are merged onto 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>
@ -160,7 +163,7 @@
<para>Thirty 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
release engineers (re@FreeBSD.org). The kinds of changes that
are allowed during this 15 day period include:</para>
<itemizedlist>
@ -197,7 +200,7 @@
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
port maintainers, to ensure that all of the
different components required for a successful release are
available.</para>
</sect2>
@ -212,11 +215,11 @@
<sect3>
<title>Creating the Release Branch</title>
<para>As described in the introduction, the RELENG_X_Y release
<para>As described in the introduction, the <literal>RELENG_X_Y</literal> release
branch is a relatively new addition to our release engineering
methodology. The first step in creating this branch is to
ensure that you are working with the newest version of the
RELENG_X sources that you want to branch
<literal>RELENG_X</literal> sources that you want to branch
<emphasis>from</emphasis>.</para>
<screen>/usr/src&prompt.root; <userinput>cvs up -rRELENG_4 -P -d</userinput></screen>
@ -232,12 +235,13 @@
<screen>/usr/src&prompt.root; <userinput>cvs rtag -b -rRELENG_4_4_BP RELENG_4_4 src</userinput></screen>
<note>
<para><emphasis>Access to these commands is restricted to the
CVS-meisters and release engineers.</emphasis></para>
<para><emphasis>The <literal>RELENG_*</literal> tags are
restricted for use by the CVS-meisters and release
engineers.</emphasis></para>
</note>
<sidebar>
<para>A <quote><emphasis>tag</emphasis></quote> is a CVS
<para>A <quote><emphasis>tag</emphasis></quote> is 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
@ -357,11 +361,11 @@
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.
<para>Occasionally, a last 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>.
tag -d <replaceable>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
@ -391,16 +395,16 @@
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>
release</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
world</command></quote> or simply
<quote><command>make
<literal>buildworld</literal></command></quote>. The release
buildworld</command></quote>. The release
target requires several variables be set properly to build a
release:</para>
@ -470,7 +474,7 @@
<listitem>
<para>Population of <filename>/etc</filename> and
<filename>/dev</filename> in the chroot<emphasis>ed</emphasis>
<filename>/dev</filename> in the chrooted
environment.</para>
</listitem>
@ -480,8 +484,8 @@
</listitem>
<listitem>
<para><quote><command>make <literal>world</literal></command></quote>
in the chroot<emphasis>ed</emphasis> environment.</para>
<para><quote><command>make world</command></quote>
in the chrooted environment.</para>
</listitem>
<listitem>
@ -499,14 +503,14 @@
<listitem>
<para>Build and installation of the documentation toolchain needed to
convert the documentation source (SGML) into HTML, and text documents
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>
and so on.)</para>
</listitem>
<listitem>
@ -543,7 +547,7 @@
This script requires that XFree86 and Tcl/Tk already be
installed on the build host. After compiling the necessary X
servers, the script will package all of the files into tarballs
that sysinstall expects to find in the
that &man.sysinstall.8; expects to find in the
<filename>XF86336</filename> directory of the installation
media.</para>
@ -559,66 +563,25 @@
<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>
collection</ulink> is a collection of over &os.numports;
third-party software packages available for FreeBSD. The ports
team (portmgr@FreeBSD.org) is responsible for maintaining a
consistent ports tree that can be used to create the binary
packages that accompany official FreeBSD releases.</para>
<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>The release engineering activities for our collection of
third-party packages is beyond the scope of this document. A
seperate article, &art.re.pkgs;, covers this topic
in depth.</para>
<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>
<title>Release ISOs</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>
<emphasis>BSDi/Wind River Systems/FreeBSD Mall</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
@ -640,10 +603,10 @@
<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
a <filename>tools</filename> 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
<filename>tools</filename> 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>
@ -677,8 +640,9 @@
<para>The remaining two discs contain 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>
included on the same disc. More information about the
creation of these discs is provided in the &art.re.pkgs;
article.</para>
</sect3>
</sect2>
</sect1>
@ -717,8 +681,7 @@
<listitem>
<para><command>rm
<literal>${CHROOTDIR}/usr/obj/usr/src/release/release.[48]</literal>
</command></para>
${CHROOTDIR}/usr/obj/usr/src/release/release.[48]</command></para>
</listitem>
<listitem>
@ -727,12 +690,12 @@
</listitem>
<listitem>
<para><command>chroot <literal>${CHROOTDIR} ./mk release.4</literal>
<para><command>chroot ${CHROOTDIR} ./mk release.4
</command></para>
</listitem>
<listitem>
<para><command>chroot <literal>${CHROOTDIR} ./mk release.8</literal>
<para><command>chroot ${CHROOTDIR} ./mk release.8
</command></para>
</listitem>
</itemizedlist>
@ -742,13 +705,13 @@
<para>Alternatively, the
<quote><filename>boot.flp</filename></quote> make
<emphasis>target</emphasis> can be called or the filesystem
target can be called, or the filesystem
creating script,
<filename>src/release/scripts/doFS.sh</filename> may be invoked
<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
defining the <makevar>LOCAL_PATCH</makevar> variable in <quote>make
release</quote>.
</para>
</sect2>
@ -775,7 +738,7 @@
<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
release candidate for the x86 architecture was released 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
@ -813,8 +776,8 @@
environment, then the CVS checkout of the ports and doc trees
can be happening simultaneously 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>
<acronym>RAID</acronym> solution (hardware or software) can
significantly decrease the overall build time.</para>
</listitem>
<listitem>