diff --git a/en_US.ISO8859-1/articles/committers-guide/article.xml b/en_US.ISO8859-1/articles/committers-guide/article.xml
index 2d1cec82d2..b60ae25089 100644
--- a/en_US.ISO8859-1/articles/committers-guide/article.xml
+++ b/en_US.ISO8859-1/articles/committers-guide/article.xml
@@ -83,16 +83,15 @@
<row>
<entry><emphasis><literal>src/</literal> Subversion
Root</emphasis></entry>
- <entry>
- <literal>svn+ssh://</literal><hostid
+ <entry><literal>svn+ssh://</literal><hostid
role="fqdn">svn.FreeBSD.org</hostid><filename>/base</filename>
(see also <xref linkend="subversion-primer"/>).</entry>
</row>
+
<row>
<entry><emphasis><literal>doc/</literal> Subversion
Root</emphasis></entry>
- <entry>
- <literal>svn+ssh://</literal><hostid
+ <entry><literal>svn+ssh://</literal><hostid
role="fqdn">svn.FreeBSD.org</hostid><filename>/doc</filename>
(see also <xref linkend="subversion-primer"/>).</entry>
</row>
@@ -100,8 +99,7 @@
<row>
<entry><emphasis><literal>ports/</literal> Subversion
Root</emphasis></entry>
- <entry>
- <literal>svn+ssh://</literal><hostid
+ <entry><literal>svn+ssh://</literal><hostid
role="fqdn">svn.FreeBSD.org</hostid><filename>/ports</filename>
(see also <xref linkend="subversion-primer"/>).</entry>
</row>
@@ -128,8 +126,7 @@
reports</emphasis></entry>
<entry><filename>/home/core/public/monthly-reports</filename>
on the <hostid role="domainname">FreeBSD.org</hostid>
- cluster.
- </entry>
+ cluster.</entry>
</row>
<row>
@@ -147,32 +144,35 @@
<entry>
<literal>stable/8</literal> (8.X-STABLE),
<literal>stable/9</literal> (9.X-STABLE),
- <literal>head</literal> (-CURRENT)
- </entry>
+ <literal>head</literal> (-CURRENT)</entry>
</row>
</tbody>
</tgroup>
</informaltable>
- <para>It is required that you use &man.ssh.1;
- to connect to the project hosts.
- If you do
- not know anything about &man.ssh.1;, please see
- <xref linkend="ssh.guide"/>.</para>
+ <para>It is required that you use &man.ssh.1; to connect to the
+ project hosts. If you do not know anything about &man.ssh.1;,
+ please see <xref linkend="ssh.guide"/>.</para>
<para>Useful links:</para>
<itemizedlist>
- <listitem><para><ulink url="&url.base;/internal/">FreeBSD
- Project Internal Pages</ulink></para></listitem>
+ <listitem>
+ <para><ulink url="&url.base;/internal/">FreeBSD
+ Project Internal Pages</ulink></para>
+ </listitem>
- <listitem><para><ulink
+ <listitem>
+ <para><ulink
url="&url.base;/internal/machines.html">FreeBSD Project
- Hosts</ulink></para></listitem>
+ Hosts</ulink></para>
+ </listitem>
- <listitem><para><ulink
+ <listitem>
+ <para><ulink
url="&url.base;/administration.html">FreeBSD Project
- Administrative Groups</ulink></para></listitem>
+ Administrative Groups</ulink></para>
+ </listitem>
</itemizedlist>
</sect1>
@@ -238,7 +238,7 @@
<sect2>
<title>Policy for <filename>doc/</filename> Committer Activity
- in <filename>src/</filename></title>
+ in <filename>src/</filename></title>
<itemizedlist>
<listitem><para>doc committers may commit documentation
@@ -274,13 +274,13 @@
operation of the version control systems in use. Traditionally
this was CVS. Subversion is used for the <literal>src</literal>
tree as of May 2008, the <literal>doc/www</literal> tree as of
- May 2012 and the <literal>ports</literal> tree as of July 2012.
- </para>
+ May 2012 and the <literal>ports</literal> tree as of July
+ 2012.</para>
<para><ulink url="http://wiki.freebsd.org/SubversionMissing">There
- is a list of things missing in Subversion when compared to CVS
- </ulink>. The notes at <ulink
- url="http://people.freebsd.org/~peter/svn_notes.txt"></ulink>
+ is a list of things missing in Subversion when compared to
+ CVS</ulink>. The notes at <ulink
+ url="http://people.freebsd.org/~peter/svn_notes.txt"></ulink>
might also be useful.</para>
<sect2 id="svn-intro">
@@ -489,26 +489,29 @@
<itemizedlist>
<listitem>
- <para><emphasis>/head/</emphasis>
- which corresponds to <literal>HEAD</literal>, also known as
- <literal>-CURRENT</literal>.
- </para>
+ <para><emphasis>/head/</emphasis> which corresponds to
+ <literal>HEAD</literal>, also known as
+ <literal>-CURRENT</literal>.</para>
</listitem>
+
<listitem>
<para><emphasis>/stable/<replaceable>n</replaceable></emphasis>
which corresponds to
<literal>RELENG_<replaceable>n</replaceable></literal>.</para>
</listitem>
+
<listitem>
<para><emphasis>/releng/<replaceable>n.n</replaceable></emphasis>
which corresponds to
<literal>RELENG_<replaceable>n_n</replaceable></literal>.</para>
</listitem>
+
<listitem>
<para><emphasis>/release/<replaceable>n.n.n</replaceable></emphasis>
which corresponds to
<literal>RELENG_<replaceable>n_n_n</replaceable>_RELEASE</literal>.</para>
</listitem>
+
<listitem>
<para><emphasis>/vendor*</emphasis> is the vendor branch
import work area. This directory itself does not
@@ -532,8 +535,8 @@
Layout</title>
<para>In <literal>svn+ssh://svn.freebsd.org/doc</literal>,
- <emphasis>doc</emphasis> refers to the repository root of the
- source tree.</para>
+ <emphasis>doc</emphasis> refers to the repository root of
+ the source tree.</para>
<para>In general, most &os; Documentation Project work will be
done within the <filename>head/</filename> branch of the
@@ -580,17 +583,20 @@
<itemizedlist>
<listitem>
- <para><emphasis>/branches/RELENG_<replaceable>n_n_n
- </replaceable></emphasis> which corresponds to
- <literal>RELENG_<replaceable>n_n_n</replaceable></literal>
+ <para><emphasis>/branches/RELENG_<replaceable>n_n_n</replaceable></emphasis>
+ which corresponds to
+ <literal>RELENG_<replaceable>n_n_n</replaceable></literal>
is used to merge back security updates in preparation
for a release.</para>
</listitem>
+
<listitem>
<para><emphasis>/tags/RELEASE_<replaceable>n_n_n</replaceable></emphasis>
- which corresponds to <literal>RELEASE_<replaceable>n_n_n</replaceable></literal>
+ which corresponds to
+ <literal>RELEASE_<replaceable>n_n_n</replaceable></literal>
represents a release tag of the ports tree.</para>
</listitem>
+
<listitem>
<para><emphasis>/tags/RELEASE_<replaceable>n</replaceable>_EOL</emphasis>
represents the end of life tag of a specific &os;
@@ -615,9 +621,9 @@
<screen>&prompt.user; <userinput>svn help</userinput></screen>
- <para>Additional information can be found in the <ulink
- url="http://svnbook.red-bean.com/">
- Subversion Book</ulink>.</para>
+ <para>Additional information can be found in the
+ <ulink url="http://svnbook.red-bean.com/">Subversion
+ Book</ulink>.</para>
</sect3>
<sect3>
@@ -717,7 +723,8 @@
<screen>&prompt.user; <userinput>svn status</userinput></screen>
- <para>To show local changes and files that are out-of-date do:</para>
+ <para>To show local changes and files that are out-of-date
+ do:</para>
<screen>&prompt.user; <userinput>svn status --show-updates</userinput></screen>
</sect3>
@@ -766,9 +773,8 @@
<command>svn rm --keep-local</command> for just added
files, fix your config file and re-add them again. The
initial config file is created when you first run a svn
- command, even something as simple as <command>svn
- help</command>.
- </para>
+ command, even something as simple as
+ <command>svn help</command>.</para>
</note>
<para>Files are added to a
@@ -1079,21 +1085,23 @@
<orderedlist>
<listitem>
- <para>If <filename
- class="directory">branch/foo/bar/</filename> does not
- already have a mergeinfo record, but a direct ancestor
- (for instance, <filename
- class="directory">branch/foo/</filename>) does,
- then that record will be propagated down to
+ <para>If
<filename class="directory">branch/foo/bar/</filename>
- before information
- about the current merge is recorded.</para>
+ does not already have a mergeinfo record, but a direct
+ ancestor (for instance,
+ <filename class="directory">branch/foo/</filename>)
+ does, then that record will be propagated down to
+ <filename class="directory">branch/foo/bar/</filename>
+ before information about the current merge is
+ recorded.</para>
</listitem>
+
<listitem>
<para>Information about the current merge will
<emphasis>not</emphasis> be propagated back up that
ancestor.</para>
</listitem>
+
<listitem>
<para>If a direct descendant of <filename
class="directory">branch/foo/bar/</filename> (for
@@ -1132,13 +1140,16 @@
<listitem>
<para>Never merge directly to a file.</para>
</listitem>
+
<listitem>
<para>Never, ever merge directly to a file.</para>
</listitem>
+
<listitem>
<para><emphasis>Never, ever, ever</emphasis> merge
directly to a file.</para>
</listitem>
+
<listitem>
<para>Changes to kernel code should be merged to
<filename class="directory">sys/</filename>. For
@@ -1151,12 +1162,14 @@
not <filename
class="directory">sys/netinet/</filename>.</para>
</listitem>
+
<listitem>
<para>Changes to code under <filename
class="directory">etc/</filename> should be merged
at <filename class="directory">etc/</filename>, not
below it.</para>
</listitem>
+
<listitem>
<para>Changes to vendor code (code in <filename
class="directory">contrib/</filename>, <filename
@@ -1169,6 +1182,7 @@
is rarely an issue, however, since changes to vendor
code are usually merged wholesale.</para>
</listitem>
+
<listitem>
<para>Changes to userland programs should as a general
rule be merged to the directory that contains the
@@ -1178,6 +1192,7 @@
should be merged to <filename
class="directory">usr.bin/xlint/</filename>.</para>
</listitem>
+
<listitem>
<para>Changes to userland libraries should as a general
rule be merged to the directory that contains the
@@ -1186,6 +1201,7 @@
should be merged to <filename
class="directory">lib/libc/</filename>.</para>
</listitem>
+
<listitem>
<para>There may be cases where it makes sense to deviate
from the rules for userland programs and libraries.
@@ -1195,12 +1211,15 @@
even though the library itself and all of the modules
each have their own Makefile.</para>
</listitem>
+
<listitem>
- <para>Changes to manual pages should be merged to <filename
+ <para>Changes to manual pages should be merged to
+ <filename
class="directory">share/man/man<replaceable>N</replaceable>/</filename>,
for the appropriate value of
<literal>N</literal>.</para>
</listitem>
+
<listitem>
<para>Other changes to <filename
class="directory">share/</filename> should be merged
@@ -1208,6 +1227,7 @@
<filename class="directory">share/</filename>
directly.</para>
</listitem>
+
<listitem>
<para>Changes to a top-level file in the source tree
such as <filename>UPDATING</filename> or
@@ -1216,6 +1236,7 @@
whole tree. Yes, this is an exception to the first
three rules.</para>
</listitem>
+
<listitem>
<para>When in doubt, ask.</para>
</listitem>
@@ -1332,21 +1353,26 @@ $target - head/$source:$P,$Q,$R</screen>
<sect5>
<title>Practical Example</title>
- <para>As a practical example, consider the following scenario:
- The changes to <filename>netmap.4</filename> in r238987 is
- to be merged from CURRENT to 9-STABLE. The file resides in
- <filename class="directory">head/share/man/man4</filename> and
- according to <xref linkend="subversion-primer-merge"/> this
- is also where to do the merge. Note that in this example
- all paths are relative to the top of the svn repository.
- for more information on the directory layout, see
+
+ <para>As a practical example, consider the following
+ scenario: The changes to <filename>netmap.4</filename>
+ in r238987 is to be merged from CURRENT to 9-STABLE.
+ The file resides in <filename
+ class="directory">head/share/man/man4</filename> and
+ according to <xref linkend="subversion-primer-merge"/>
+ this is also where to do the merge. Note that in this
+ example all paths are relative to the top of the svn
+ repository. for more information on the directory
+ layout, see
<xref linkend="subversion-primer-base-layout"/>.</para>
- <para>The first step is to inspect the existing mergeinfo.</para>
+
+ <para>The first step is to inspect the existing
+ mergeinfo.</para>
<screen>&prompt.user; <userinput>svn propget svn:mergeinfo -R stable/9/share/man/man4</userinput></screen>
- <para>Take a quick note of how it looks before moving on to the next
- step; doing the actual merge:</para>
+ <para>Take a quick note of how it looks before moving on
+ to the next step; doing the actual merge:</para>
<screen>&prompt.user; <userinput>svn merge -c r238987 svn+ssh://svn.freebsd.org/base/head/share/man/man4 stable/9/share/man/man4</userinput>
--- Merging r238987 into 'stable/9/share/man/man4':
@@ -1355,11 +1381,11 @@ U stable/9/share/man/man4/netmap.4
'stable/9/share/man/man4':
U stable/9/share/man/man4</screen>
- <para>Check that the revision number of the merged revision
- has been added. Once this is verified, the only thing left
- is the actual commit.</para>
-
- <screen>&prompt.user; <userinput>svn commit stable/9/share/man/man4</userinput></screen>
+ <para>Check that the revision number of the merged
+ revision has been added. Once this is verified, the
+ only thing left is the actual commit.</para>
+
+ <screen>&prompt.user; <userinput>svn commit stable/9/share/man/man4</userinput></screen>
</sect5>
<sect5>
@@ -1419,24 +1445,26 @@ U stable/9/share/man/man4/netmap.4
<title>Vendor Imports with <acronym>SVN</acronym></title>
<important>
- <para>Please read this entire section before starting a vendor
- import.</para>
+ <para>Please read this entire section before starting a
+ vendor import.</para>
</important>
<note>
- <para>Patches to vendor code fall into two categories:</para>
+ <para>Patches to vendor code fall into two
+ categories:</para>
<itemizedlist>
<listitem>
<para>Vendor patches: these are patches that have been
- issued by the vendor, or that have been extracted from
- the vendor's version control system, which address
- issues which in your opinion cannot wait until the next
- vendor release.</para>
+ issued by the vendor, or that have been extracted from
+ the vendor's version control system, which address
+ issues which in your opinion cannot wait until the
+ next vendor release.</para>
</listitem>
+
<listitem>
<para>&os; patches: these are patches that modify the
- vendor code to address &os;-specific issues.</para>
+ vendor code to address &os;-specific issues.</para>
</listitem>
</itemizedlist>
@@ -1446,17 +1474,18 @@ U stable/9/share/man/man4/netmap.4
<itemizedlist>
<listitem>
<para>Vendor patches should be committed to the vendor
- branch, and merged from there to head. If the patch
- addresses an issue in a new release that is currently
- being imported, it <emphasis>must not</emphasis> be
- committed along with the new release: the release must
- be imported and tagged first, then the patch can be
- applied and committed. There is no need to re-tag the
- vendor sources after committing the patch.</para>
+ branch, and merged from there to head. If the patch
+ addresses an issue in a new release that is currently
+ being imported, it <emphasis>must not</emphasis> be
+ committed along with the new release: the release must
+ be imported and tagged first, then the patch can be
+ applied and committed. There is no need to re-tag the
+ vendor sources after committing the patch.</para>
</listitem>
+
<listitem>
<para>&os; patches should be committed directly to
- head.</para>
+ head.</para>
</listitem>
</itemizedlist>
</note>
@@ -1509,22 +1538,22 @@ U stable/9/share/man/man4/netmap.4
as necessary. Disabling keyword expansion is
recommended, as it makes no sense on unmodified vendor
code and in some cases it can even be harmful.
- <application>OpenSSH</application>, for example, includes
- two files that originated with &os; and still contain the
- original version tags. To do this:</para>
+ <application>OpenSSH</application>, for example,
+ includes two files that originated with &os; and still
+ contain the original version tags. To do this:</para>
<screen>&prompt.user; <userinput>svn propdel svn:keywords -R .</userinput>
&prompt.root; <userinput>svn commit</userinput></screen>
</sect5>
+
<sect5>
<title>Bootstrapping Merge History</title>
<para>If importing for the first time after the switch to
- Subversion, bootstrap
- <literal>svn:mergeinfo</literal> on the target directory
- in the main tree to the revision that corresponds
- to the last related change to the vendor tree, prior to
- importing new sources:</para>
+ Subversion, bootstrap <literal>svn:mergeinfo</literal>
+ on the target directory in the main tree to the revision
+ that corresponds to the last related change to the
+ vendor tree, prior to importing new sources:</para>
<screen>&prompt.user; <userinput>cd <replaceable>head/contrib/pf</replaceable></userinput>
&prompt.user; <userinput>svn merge --record-only svn+ssh://svn.freebsd.org/base/<replaceable>vendor/pf/dist@180876</replaceable> .</userinput>
@@ -1543,11 +1572,11 @@ U stable/9/share/man/man4/netmap.4
<sect5>
<title>Preparing the Vendor Sources</title>
- <para>Unlike in <acronym>CVS</acronym> where only the needed
- parts were imported into the vendor tree to avoid bloating
- the main tree, Subversion is able to store a full
- distribution in the vendor tree. So, import everything,
- but merge only what is required.</para>
+ <para>Unlike in <acronym>CVS</acronym> where only the
+ needed parts were imported into the vendor tree to avoid
+ bloating the main tree, Subversion is able to store a
+ full distribution in the vendor tree. So, import
+ everything, but merge only what is required.</para>
<para>A <command>svn add</command> is required to add any
files that were added since the last vendor import, and
@@ -1563,12 +1592,13 @@ U stable/9/share/man/man4/netmap.4
&prompt.user; <userinput>find . -type f | cut -c 3- | sort >../new</userinput></screen>
<para>With these two files,
- <command>comm -23 ../old ../new</command>
- will list removed files (files only in
- <filename>old</filename>), while
- <command>comm -13 ../old ../new</command>
- will list added files only in <filename>new</filename>.</para>
+ <command>comm -23 ../old ../new</command> will list
+ removed files (files only in <filename>old</filename>),
+ while <command>comm -13 ../old ../new</command> will
+ list added files only in
+ <filename>new</filename>.</para>
</sect5>
+
<sect5>
<title>Importing into the Vendor Tree</title>
@@ -1584,17 +1614,18 @@ U stable/9/share/man/man4/netmap.4
&prompt.user; <userinput>comm -23 ../old ../new | xargs svn rm</userinput>
&prompt.user; <userinput>comm -13 ../old ../new | xargs svn --parents add</userinput></screen>
- <para>If any directories were removed, they will have to be
- <command>svn rm</command>ed manually. Nothing will break
- if they are not, but they will remain in the tree.</para>
+ <para>If any directories were removed, they will have to
+ be <command>svn rm</command>ed manually. Nothing will
+ break if they are not, but they will remain in the
+ tree.</para>
- <para>Check properties on any new files. All text files
+ <para>Check properties on any new files. All text files
should have <literal>svn:eol-style</literal> set to
<literal>native</literal>. All binary files should have
<literal>svn:mime-type</literal> set to
<literal>application/octet-stream</literal> unless there
- is a more appropriate media type. Executable files should
- have <literal>svn:executable</literal> set to
+ is a more appropriate media type. Executable files
+ should have <literal>svn:executable</literal> set to
<literal>*</literal>. No other properties should exist
on any file in the tree.</para>
@@ -1619,13 +1650,15 @@ U stable/9/share/man/man4/netmap.4
needed.</para>
<para>If creating the tag in the working copy of the tree,
- <command>svn:mergeinfo</command> results must be removed:</para>
+ <command>svn:mergeinfo</command> results must be
+ removed:</para>
<screen>&prompt.user; <userinput>cd <replaceable>vendor/pf</replaceable></userinput>
&prompt.user; <userinput>svn cp dist 4.3</userinput>
&prompt.user; <userinput>svn propdel svn:mergeinfo -R 4.3</userinput></screen>
</sect5>
</sect4>
+
<sect4>
<title>Merging to Head</title>
@@ -1634,8 +1667,8 @@ U stable/9/share/man/man4/netmap.4
&prompt.user; <userinput>svn merge --accept=postpone svn+ssh://svn.freebsd.org/base/<replaceable>vendor/pf/dist</replaceable> .</userinput></screen>
<para>The <literal>--accept=postpone</literal> tells
- Subversion that it should not complain because merge conflicts
- will be taken care of manually.</para>
+ Subversion that it should not complain because merge
+ conflicts will be taken care of manually.</para>
<para>It is necessary to resolve any merge conflicts.
This process is the same in <acronym>SVN</acronym> as in
@@ -1643,7 +1676,8 @@ U stable/9/share/man/man4/netmap.4
<para>Make sure that any files that were added or removed in
the vendor tree have been properly added or removed in the
- main tree. To check diffs against the vendor branch:</para>
+ main tree. To check diffs against the vendor
+ branch:</para>
<screen>&prompt.user; <userinput>svn diff --no-diff-deleted --old=svn+ssh://svn.freebsd.org/base/<replaceable>vendor/pf/dist</replaceable> --new=.</userinput></screen>
@@ -1659,13 +1693,15 @@ U stable/9/share/man/man4/netmap.4
Subversion, there is no concept of on or off the vendor
branch. If a file that previously had local
modifications, to make it not show up in diffs in the
- vendor tree, all that has to be done is remove any left-over
- cruft like &os; version tags, which is much easier.</para>
+ vendor tree, all that has to be done is remove any
+ left-over cruft like &os; version tags, which is much
+ easier.</para>
<para>If any changes are required for the world to build
with the new sources, make them now, and keep testing
until everything builds and runs perfectly.</para>
</sect4>
+
<sect4>
<title>Committing the Vendor Import</title>
@@ -1694,11 +1730,11 @@ U stable/9/share/man/man4/netmap.4
&prompt.user; <userinput>svn mkdir <replaceable>byacc/dist</replaceable></userinput></screen>
<para>Now, import the sources into the
- <filename class="directory">dist</filename> directory. Once
- the files are in place, <command>svn add</command> the new
- ones, then <command>svn commit</command> and tag the
- imported version. To save time and bandwidth, direct remote
- committing and tagging is possible:</para>
+ <filename class="directory">dist</filename> directory.
+ Once the files are in place, <command>svn add</command>
+ the new ones, then <command>svn commit</command> and tag
+ the imported version. To save time and bandwidth,
+ direct remote committing and tagging is possible:</para>
<screen>&prompt.user; <userinput>svn cp -m <replaceable>"Tag byacc 20120115"</replaceable> <replaceable>$FSVN/vendor/byacc/dist</replaceable> <replaceable>$FSVN/vendor/byacc/20120115</replaceable></userinput></screen>
</sect5>
@@ -1715,9 +1751,9 @@ U stable/9/share/man/man4/netmap.4
possible.</para>
</sect5>
</sect4>
- </sect3>
+ </sect3>
- <sect3>
+ <sect3>
<title>Reverting a Commit</title>
<para>Reverting a commit to a previous version is fairly
@@ -1906,8 +1942,8 @@ U stable/9/share/man/man4/netmap.4
<para>Do not remove and re-add the same file in a single commit
as this will break the CVS exporter.</para>
- <para>Speeding up svn is
- possible by adding the following to <filename>~/.ssh/config</filename>:</para>
+ <para>Speeding up svn is possible by adding the following to
+ <filename>~/.ssh/config</filename>:</para>
<screen>Host *
ControlPath ~/.ssh/sockets/master-%l-%r@%h:%p
@@ -1919,10 +1955,10 @@ ControlPersist yes</screen>
<para>Checking out a working copy with a stock Subversion client
without &os;-specific patches
- (<makevar>OPTIONS_SET=FREEBSD_TEMPLATE</makevar>) will mean that
- <literal>$FreeBSD$</literal> tags will not be
- expanded. Once the correct version has been installed, trick
- Subversion into expanding them like so:</para>
+ (<makevar>OPTIONS_SET=FREEBSD_TEMPLATE</makevar>) will mean
+ that <literal>$FreeBSD$</literal> tags will not
+ be expanded. Once the correct version has been installed,
+ trick Subversion into expanding them like so:</para>
<screen>&prompt.user; <userinput>svn propdel -R svn:keywords .</userinput>
&prompt.user; <userinput>svn revert -R .</userinput></screen>
@@ -1934,10 +1970,10 @@ ControlPersist yes</screen>
<sect1 id="conventions">
<title>Conventions and Traditions</title>
- <para>As a new developer there are a number of things you should do
- first. The first set is specific to committers only. (If you are
- not a committer, e.g., have GNATS-only access, then your mentor needs
- to do these things for you.)</para>
+ <para>As a new developer there are a number of things you should
+ do first. The first set is specific to committers only. (If
+ you are not a committer, e.g., have GNATS-only access, then your
+ mentor needs to do these things for you.)</para>
<sect2 id="conventions-committers">
<title>Guidelines for Committers</title>
@@ -1952,130 +1988,139 @@ ControlPersist yes</screen>
<para>If you have been given commit rights to one or more of the
repositories:</para>
- <itemizedlist>
- <listitem>
- <para>Add your author entity to
- <filename>head/share/xml/authors.ent</filename>;
- this should be done first since an omission of this commit will
- cause the next commits to break the doc/ build.</para>
+ <itemizedlist>
+ <listitem>
+ <para>Add your author entity to
+ <filename>head/share/xml/authors.ent</filename>; this
+ should be done first since an omission of this commit will
+ cause the next commits to break the doc/ build.</para>
- <para>This is a relatively easy task, but remains a good first test of
- your version control skills.</para>
+ <para>This is a relatively easy task, but remains a good
+ first test of your version control skills.</para>
- <important>
- <para>New files that do not have the
- <literal>FreeBSD=%H</literal> <command>svn:keywords</command>
- property will be rejected when attempting to commit them to the
- repository. Be sure to read <xref
- linkend="subversion-primer-add-remove"/>
- regarding adding and removing files, in addition
- to verifying that <filename>~/.subversion/config</filename>
- contains the necessary "auto-props"
- entries from <filename>auto-props.txt</filename> mentioned
- there.</para>
- </important>
+ <important>
+ <para>New files that do not have the
+ <literal>FreeBSD=%H</literal>
+ <command>svn:keywords</command> property will be
+ rejected when attempting to commit them to the
+ repository. Be sure to read
+ <xref linkend="subversion-primer-add-remove"/> regarding
+ adding and removing files, in addition to verifying that
+ <filename>~/.subversion/config</filename> contains the
+ necessary "auto-props" entries from
+ <filename>auto-props.txt</filename> mentioned
+ there.</para>
+ </important>
- <note>
- <para>Do not forget to get mentor approval for these patches!</para>
- </note>
+ <note>
+ <para>Do not forget to get mentor approval for these
+ patches!</para>
+ </note>
+ </listitem>
- </listitem>
+ <listitem>
+ <para>Also add your author entity to
+ <filename>head/share/xml/developers.ent</filename>.</para>
+ </listitem>
- <listitem>
- <para>Also add your author entity to
- <filename>head/share/xml/developers.ent</filename>.</para>
- </listitem>
+ <listitem>
+ <para>Add yourself to the <quote>Developers</quote> section
+ of the <ulink
+ url="&url.articles.contributors;/index.html">Contributors
+ List</ulink>
+ (<filename>head/en_US.ISO8859-1/articles/contributors/contrib.committers.xml</filename>)
+ and remove yourself from the
+ <quote>Additional Contributors</quote> section
+ (<filename>head/en_US.ISO8859-1/articles/contributors/contrib.additional.xml</filename>).
+ Please note that entries are sorted by last name.</para>
+ </listitem>
- <listitem>
- <para>Add yourself to the <quote>Developers</quote> section of
- the <ulink url="&url.articles.contributors;/index.html">Contributors List</ulink>
- (<filename>head/en_US.ISO8859-1/articles/contributors/contrib.committers.xml</filename>) and remove yourself from the <quote>Additional
- Contributors</quote> section (<filename>head/en_US.ISO8859-1/articles/contributors/contrib.additional.xml</filename>).
- Please note that entries are sorted by last name.</para>
- </listitem>
+ <listitem>
+ <para>Add an entry for yourself to
+ <filename>head/share/xml/news.xml</filename>. Look for
+ the other entries that look like
+ <quote>A new committer</quote> and follow the
+ format.</para>
+ </listitem>
- <listitem>
- <para>Add an entry for yourself to
- <filename>head/share/xml/news.xml</filename>. Look for the other
- entries that look like <quote>A new committer</quote> and follow the
- format.</para>
- </listitem>
+ <listitem>
+ <para>You should add your PGP or GnuPG key to
+ <filename>head/share/pgpkeys</filename> (and if you do not
+ have a key, you should create one). Do not forget to
+ commit the updated
+ <filename>head/share/pgpkeys/pgpkeys.ent</filename> and
+ <filename>head/share/pgpkeys/pgpkeys-developers.xml</filename>.
+ Please note that entries are sorted by last name.</para>
- <listitem>
- <para>You should add your PGP or GnuPG key to
- <filename>head/share/pgpkeys</filename> (and if you do not
- have a key, you should create one). Do not forget to commit
- the updated <filename>head/share/pgpkeys/pgpkeys.ent</filename>
- and <filename>head/share/pgpkeys/pgpkeys-developers.xml</filename>.
- Please note that entries are sorted by last name.</para>
+ <para>&a.des; has written a shell script
+ (<filename>head/share/pgpkeys/addkey.sh</filename>) to
+ make this extremely simple. See the <ulink
+ url="http://svnweb.FreeBSD.org/doc/head/share/pgpkeys/README">README</ulink>
+ file for more information.</para>
- <para>&a.des; has
- written a shell script (<filename>head/share/pgpkeys/addkey.sh</filename>) to make this extremely simple. See the
- <ulink
- url="http://svnweb.FreeBSD.org/doc/head/share/pgpkeys/README">README</ulink>
- file for more information.</para>
+ <note>
+ <para>It is important to have an up-to-date PGP/GnuPG key
+ in the Handbook, since the key may be required for
+ positive identification of a committer, e.g., by the
+ &a.admins; for account recovery. A complete keyring of
+ <hostid role="domainname">FreeBSD.org</hostid> users is
+ available for download from <ulink
+ url="&url.base;/doc/pgpkeyring.txt">http://www.FreeBSD.org/doc/pgpkeyring.txt</ulink>.</para>
+ </note>
+ </listitem>
- <note>
- <para>It is important to have an up-to-date PGP/GnuPG key in
- the Handbook, since the key may be required for positive
- identification of a committer, e.g., by the &a.admins; for
- account recovery. A complete keyring of <hostid
- role="domainname">FreeBSD.org</hostid> users is available
- for download from <ulink
- url="&url.base;/doc/pgpkeyring.txt">http://www.FreeBSD.org/doc/pgpkeyring.txt</ulink>.</para>
- </note>
- </listitem>
+ <listitem>
+ <para>Add an entry for yourself to
+ <filename>src/share/misc/committers-<replaceable>repository</replaceable>.dot</filename>,
+ where repository is either doc, ports or src, depending on
+ the commit privileges you obtained.</para>
+ </listitem>
- <listitem>
- <para>Add an entry for yourself to
- <filename>src/share/misc/committers-<replaceable>repository</replaceable>.dot</filename>,
- where repository is either doc, ports or src, depending on the commit privileges
- you obtained.</para>
- </listitem>
+ <listitem>
+ <para>Some people add an entry for themselves to
+ <filename>ports/astro/xearth/files/freebsd.committers.markers</filename>.</para>
+ </listitem>
- <listitem>
- <para>Some people add an entry for themselves to
- <filename>ports/astro/xearth/files/freebsd.committers.markers</filename>.</para>
- </listitem>
+ <listitem>
+ <para>Some people add an entry for themselves to
+ <filename>src/usr.bin/calendar/calendars/calendar.freebsd</filename>.</para>
+ </listitem>
- <listitem>
- <para>Some people add an entry for themselves to
- <filename>src/usr.bin/calendar/calendars/calendar.freebsd</filename>.</para>
- </listitem>
+ <listitem>
+ <para>If you already have an account at the
+ <ulink url="http://wiki.freebsd.org">&os; wiki</ulink>,
+ make sure your mentor moves you from the <ulink
+ url="http://wiki.freebsd.org/ContributorsGroup">Contributors
+ group</ulink> to the <ulink
+ url="http://wiki.freebsd.org/DevelopersGroup">Developers
+ group</ulink>. Otherwise, consider signing up for an
+ account so you can publish projects and ideas you are
+ working on.</para>
+ </listitem>
- <listitem>
- <para>If you already have an account at the <ulink url="http://wiki.freebsd.org">&os; wiki</ulink>,
- make sure your mentor moves you from the
- <ulink url="http://wiki.freebsd.org/ContributorsGroup">Contributors group</ulink>
- to the
- <ulink url="http://wiki.freebsd.org/DevelopersGroup">Developers group</ulink>.
- Otherwise, consider signing up for an account so you can publish
- projects and ideas you are working on.</para>
- </listitem>
+ <listitem>
+ <para>Once you get access to the wiki, you may add yourself
+ to the
+ <ulink url="http://wiki.freebsd.org/HowWeGotHere">How We
+ Got Here</ulink> and
+ <ulink url="http://wiki.freebsd.org/IrcNicks">Irc
+ Nicks</ulink> pages.</para>
+ </listitem>
- <listitem>
- <para>Once you get access to the wiki, you may
- add yourself to the <ulink
- url="http://wiki.freebsd.org/HowWeGotHere">How We Got
- Here</ulink> and <ulink
- url="http://wiki.freebsd.org/IrcNicks">Irc Nicks</ulink>
- pages.</para>
- </listitem>
+ <listitem>
+ <para>If you subscribe to &a.svn-src-all.name;,
+ &a.svn-ports-all.name; or &a.svn-doc-all.name;, you will
+ probably want to unsubscribe to avoid receiving duplicate
+ copies of commit messages and their followups.</para>
+ </listitem>
+ </itemizedlist>
- <listitem>
- <para>If you subscribe to &a.svn-src-all.name;,
- &a.svn-ports-all.name; or &a.svn-doc-all.name;,
- you will probably want to unsubscribe to avoid receiving duplicate
- copies of commit messages and their followups.</para>
- </listitem>
- </itemizedlist>
-
- <note>
- <para>All <filename>src</filename> commits should go to
- &os.current; first before being merged to &os.stable;. No major
- new features or high-risk modifications should be made to the
- &os.stable; branch.</para>
- </note>
+ <note>
+ <para>All <filename>src</filename> commits should go to
+ &os.current; first before being merged to &os.stable;. No
+ major new features or high-risk modifications should be made
+ to the &os.stable; branch.</para>
+ </note>
</sect2>
<sect2 id="conventions-everyone">
@@ -2083,69 +2128,72 @@ ControlPersist yes</screen>
<para>Whether or not you have commit rights:</para>
- <itemizedlist>
- <listitem>
- <para>Introduce yourself to the other developers, otherwise no one
- will have any idea who you are or what you are working on. You do
- not have to write a comprehensive biography, just write a paragraph
- or two about who you are and what you plan to be working on as a
- developer in FreeBSD. (You should also mention who your mentor
- will be). Email this to the &a.developers; and you will
- be on your way!</para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para>Introduce yourself to the other developers, otherwise
+ no one will have any idea who you are or what you are
+ working on. You do not have to write a comprehensive
+ biography, just write a paragraph or two about who you are
+ and what you plan to be working on as a developer in
+ FreeBSD. (You should also mention who your mentor will
+ be). Email this to the &a.developers; and you will be on
+ your way!</para>
+ </listitem>
- <listitem>
- <para>Log into <hostid>hub.FreeBSD.org</hostid> and create a
- <filename>/var/forward/<replaceable>user</replaceable></filename>
- (where <replaceable>user</replaceable> is your username) file
- containing the e-mail address where you want mail addressed to
- <replaceable>yourusername</replaceable>@FreeBSD.org to be forwarded.
- This includes all of the commit messages as well as any other mail
- addressed to the &a.committers; and the &a.developers;. Really
- large mailboxes which have taken up permanent residence on
- <hostid>hub</hostid> often get <quote>accidentally</quote> truncated
- without warning, so forward it or read it and you will not lose
- it.</para>
+ <listitem>
+ <para>Log into <hostid>hub.FreeBSD.org</hostid> and create a
+ <filename>/var/forward/<replaceable>user</replaceable></filename>
+ (where <replaceable>user</replaceable> is your username)
+ file containing the e-mail address where you want mail
+ addressed to
+ <replaceable>yourusername</replaceable>@FreeBSD.org to be
+ forwarded. This includes all of the commit messages as
+ well as any other mail addressed to the &a.committers; and
+ the &a.developers;. Really large mailboxes which have
+ taken up permanent residence on <hostid>hub</hostid> often
+ get <quote>accidentally</quote> truncated without warning,
+ so forward it or read it and you will not lose it.</para>
- <para>Due to the severe load dealing with SPAM places on
- the central mail servers that do the mailing list processing
- the front-end server does do some basic checks and will
- drop some messages based on these checks. At the moment
- proper DNS information for the connecting host is the only
- check in place but that may change. Some people blame these
- checks for bouncing valid email. If you want these checks
- turned off for your email you can place a file named
- <filename>.spam_lover</filename> in your home directory
- on <hostid role="fqdn">freefall.FreeBSD.org</hostid> to
- disable the checks for your email.</para>
- </listitem>
- </itemizedlist>
+ <para>Due to the severe load dealing with SPAM places on the
+ central mail servers that do the mailing list processing
+ the front-end server does do some basic checks and will
+ drop some messages based on these checks. At the moment
+ proper DNS information for the connecting host is the only
+ check in place but that may change. Some people blame
+ these checks for bouncing valid email. If you want these
+ checks turned off for your email you can place a file
+ named <filename>.spam_lover</filename> in your home
+ directory on
+ <hostid role="fqdn">freefall.FreeBSD.org</hostid> to
+ disable the checks for your email.</para>
+ </listitem>
+ </itemizedlist>
- <note>
- <para>If you are a developer but not a committer, you will
- not be subscribed to the committers or developers mailing lists;
- the subscriptions are derived from the access rights.</para>
- </note>
+ <note>
+ <para>If you are a developer but not a committer, you will
+ not be subscribed to the committers or developers mailing
+ lists; the subscriptions are derived from the access
+ rights.</para>
+ </note>
</sect2>
<sect2 id="mentors">
<title>Mentors</title>
- <para>All new developers also have a mentor assigned to them for
- the first few months. Your mentor is responsible for teaching
- you the rules and conventions of the project and guiding your
- first steps in the developer community. Your mentor is also
- personally responsible for your actions during this initial
- period.</para>
+ <para>All new developers also have a mentor assigned to them for
+ the first few months. Your mentor is responsible for teaching
+ you the rules and conventions of the project and guiding your
+ first steps in the developer community. Your mentor is also
+ personally responsible for your actions during this initial
+ period.</para>
- <para>For committers: until your
- mentor decides (and announces with a forced
- commit to <filename>access</filename>) that you have learned the
- ropes and are ready to commit on your own, you should not commit
- anything without first getting your mentor's review and
- approval, and you should document that approval with an
- <literal>Approved by:</literal> line in the commit
- message.</para>
+ <para>For committers: until your mentor decides (and announces
+ with a forced commit to <filename>access</filename>) that you
+ have learned the ropes and are ready to commit on your own,
+ you should not commit anything without first getting your
+ mentor's review and approval, and you should document that
+ approval with an <literal>Approved by:</literal> line in the
+ commit message.</para>
</sect2>
</sect1>
@@ -2155,7 +2203,7 @@ ControlPersist yes</screen>
<para>Currently the &os; Project suggests and uses the following
text as the preferred license scheme:</para>
-<programlisting>/*-
+ <programlisting>/*-
* Copyright (c) [year] [your name]
* All rights reserved.
*
@@ -2199,20 +2247,19 @@ ControlPersist yes</screen>
utilize this code, typically from unintended consequences from a
poorly worded license.</para>
- <para>Project policy dictates that code under some non-BSD licenses
- must be placed only in specific sections of the repository, and
- in some cases, compilation must be conditional or even disabled
- by default. For example, the GENERIC kernel must be compiled
- under only licenses identical to or substantially similar to the
- BSD license. GPL, APSL, CDDL, etc, licensed software must not be
- compiled into GENERIC.</para>
+ <para>Project policy dictates that code under some non-BSD
+ licenses must be placed only in specific sections of the
+ repository, and in some cases, compilation must be conditional
+ or even disabled by default. For example, the GENERIC kernel
+ must be compiled under only licenses identical to or
+ substantially similar to the BSD license. GPL, APSL, CDDL, etc,
+ licensed software must not be compiled into GENERIC.</para>
<para>Developers are reminded that in open source, getting "open"
- right is just as important as getting "source" right, as improper
- handling of intellectual property has serious consequences. Any
- questions or concerns should immediately be brought to the
- attention of the core team.</para>
-
+ right is just as important as getting "source" right, as
+ improper handling of intellectual property has serious
+ consequences. Any questions or concerns should immediately be
+ brought to the attention of the core team.</para>
</sect1>
<sect1 id="developer.relations">
@@ -2226,23 +2273,22 @@ ControlPersist yes</screen>
areas, to our shame), the same applies. If, however, you are
about to modify something which is clearly being actively
maintained by someone else (and it is only by watching the
- <literal><replaceable>repository</replaceable>-committers</literal> mailing list that you can
- really get a feel for just what is and is not) then consider
- sending the change to them instead, just as you would have
- before becoming a committer. For ports, you should contact the
- listed <makevar>MAINTAINER</makevar> in the
+ <literal><replaceable>repository</replaceable>-committers</literal>
+ mailing list that you can really get a feel for just what is and
+ is not) then consider sending the change to them instead, just
+ as you would have before becoming a committer. For ports, you
+ should contact the listed <makevar>MAINTAINER</makevar> in the
<filename>Makefile</filename>. For other parts of the
repository, if you are unsure who the active maintainer might
- be, it may help to scan the revision history
- to see who has committed changes in the past. &a.fenner; has
- written a nice shell script that can help determine who the
- active maintainer might be. It lists each person who has
- committed to a given file along with the number of commits each
- person has made. It can be found on <hostid>freefall</hostid>
- at <filename>~fenner/bin/whodid</filename>. If your queries go
+ be, it may help to scan the revision history to see who has
+ committed changes in the past. &a.fenner; has written a nice
+ shell script that can help determine who the active maintainer
+ might be. It lists each person who has committed to a given
+ file along with the number of commits each person has made. It
+ can be found on <hostid>freefall</hostid> at
+ <filename>~fenner/bin/whodid</filename>. If your queries go
unanswered or the committer otherwise indicates a lack of
- interest in the area affected, go ahead and commit
- it.</para>
+ interest in the area affected, go ahead and commit it.</para>
<para>If you are unsure about a commit for any reason at
all, have it reviewed by <literal>-hackers</literal>
@@ -2250,8 +2296,8 @@ ControlPersist yes</screen>
rather than when it is part of the repository. If you do
happen to commit something which results in controversy
erupting, you may also wish to consider backing the change out
- again until the matter is settled. Remember – with a version control system we
- can always change it back.</para>
+ again until the matter is settled. Remember – with a
+ version control system we can always change it back.</para>
<para>Do not impugn the intentions of someone you disagree with.
If they see a different solution to a problem than you, or even
@@ -2298,15 +2344,19 @@ ControlPersist yes</screen>
<itemizedlist>
<listitem>
- <para><ulink url="&url.articles.pr-guidelines;/index.html">FreeBSD Problem Report Handling Guidelines</ulink></para>
+ <para><ulink
+ url="&url.articles.pr-guidelines;/index.html">FreeBSD
+ Problem Report Handling Guidelines</ulink></para>
</listitem>
<listitem>
- <para><ulink url="http://www.cs.utah.edu/csinfo/texinfo/gnats/gnats.html"></ulink></para>
+ <para><ulink
+ url="http://www.cs.utah.edu/csinfo/texinfo/gnats/gnats.html"></ulink></para>
</listitem>
<listitem>
- <para><ulink url="&url.base;/support.html">http://www.FreeBSD.org/support.html</ulink></para>
+ <para><ulink
+ url="&url.base;/support.html">http://www.FreeBSD.org/support.html</ulink></para>
</listitem>
<listitem>
@@ -2314,20 +2364,20 @@ ControlPersist yes</screen>
</listitem>
</itemizedlist>
- <para>You can run a local copy of GNATS, and then integrate the FreeBSD
- GNATS tree by creating an <application>rsync</application> mirror.
- Then you can run GNATS commands locally, allowing you to query the PR
- database without an Internet connection.</para>
+ <para>You can run a local copy of GNATS, and then integrate the
+ FreeBSD GNATS tree by creating an
+ <application>rsync</application> mirror. Then you can run GNATS
+ commands locally, allowing you to query the PR database without
+ an Internet connection.</para>
<sect2>
<title>Mirroring the GNATS Tree</title>
<para>It is possible to mirror the GNATS database by installing
<filename role="package">net/rsync</filename>, and
- executing:</para>
+ executing:</para>
<screen>&prompt.user; <userinput>rsync -va rsync://bit0.us-west.freebsd.org/FreeBSD-bit/gnats .</userinput></screen>
-
</sect2>
<sect2 id="gnatstools">
@@ -2335,8 +2385,8 @@ ControlPersist yes</screen>
<para>Other than <command>edit-pr</command> there are a
collection of tools in <filename>~gnats/tools/</filename>
- on <hostid>freefall</hostid> which can make
- working with PRs much easier.</para>
+ on <hostid>freefall</hostid> which can make working with PRs
+ much easier.</para>
<para><command>open-pr</command>, <command>close-pr</command>,
<command>take-pr</command>, and <command>feedback-pr</command>
@@ -2355,32 +2405,34 @@ ControlPersist yes</screen>
<command>change-pr -t -p -m "awaiting MFC"
<replaceable>123456</replaceable></command></para>
</sect2>
- </sect1>
+ </sect1>
<sect1 id="people">
<title>Who's Who</title>
- <para>Besides the repository
- meisters, there are other FreeBSD project members and teams whom you will
- probably get to know in your role as a committer. Briefly,
- and by no means all-inclusively, these are:</para>
+ <para>Besides the repository meisters, there are other FreeBSD
+ project members and teams whom you will probably get to know in
+ your role as a committer. Briefly, and by no means
+ all-inclusively, these are:</para>
<variablelist>
-
<varlistentry>
<term>&a.doceng;</term>
<listitem>
- <para>doceng is the group responsible for the documentation build
- infrastructure, approving new documentation committers, and
- ensuring that the FreeBSD website and documentation on the FTP
- site is up to date with respect to the CVS tree. It is not a
- conflict resolution body. The vast majority of documentation
- related discussion takes place on the &a.doc;. More details regarding the doceng team can be found in its <ulink url="http://www.FreeBSD.org/internal/doceng.html">charter</ulink>. Committers
- interested in contributing to the documentation should familiarize
- themselves with the <ulink
- url="&url.books.fdp-primer;/index.html">Documentation Project
- Primer</ulink>.</para>
+ <para>doceng is the group responsible for the documentation
+ build infrastructure, approving new documentation
+ committers, and ensuring that the FreeBSD website and
+ documentation on the FTP site is up to date with respect
+ to the CVS tree. It is not a conflict resolution body.
+ The vast majority of documentation related discussion
+ takes place on the &a.doc;. More details regarding the
+ doceng team can be found in its <ulink
+ url="http://www.FreeBSD.org/internal/doceng.html">charter</ulink>.
+ Committers interested in contributing to the documentation
+ should familiarize themselves with the <ulink
+ url="&url.books.fdp-primer;/index.html">Documentation
+ Project Primer</ulink>.</para>
</listitem>
</varlistentry>
@@ -2389,8 +2441,8 @@ ControlPersist yes</screen>
<listitem>
<para>Ruslan is Mister &man.mdoc.7;. If you are writing a
- manual page and need
- some advice on the structure, or the markup, ask Ruslan.</para>
+ manual page and need some advice on the structure, or the
+ markup, ask Ruslan.</para>
</listitem>
</varlistentry>
@@ -2398,11 +2450,11 @@ ControlPersist yes</screen>
<term>&a.bde;</term>
<listitem>
- <para>Bruce is the Style Police-Meister.
- When you do a commit that could have been done better,
- Bruce will be there to tell you. Be thankful that someone
- is. Bruce is also very knowledgeable on the various
- standards applicable to FreeBSD.</para>
+ <para>Bruce is the Style Police-Meister. When you do a
+ commit that could have been done better, Bruce will be
+ there to tell you. Be thankful that someone is. Bruce is
+ also very knowledgeable on the various standards
+ applicable to FreeBSD.</para>
</listitem>
</varlistentry>
@@ -2421,9 +2473,9 @@ ControlPersist yes</screen>
<para>Hiroki is also the keeper of the release documentation
(<filename>src/release/doc/*</filename>). If you commit a
- change that you think is worthy of mention in the release notes,
- please make sure he knows about it. Better still, send him
- a patch with your suggested commentary.</para>
+ change that you think is worthy of mention in the release
+ notes, please make sure he knows about it. Better still,
+ send him a patch with your suggested commentary.</para>
</listitem>
</varlistentry>
@@ -2432,10 +2484,9 @@ ControlPersist yes</screen>
<listitem>
<para>Dag-Erling is the
- <ulink url="&url.base;/security/">FreeBSD Security
- Officer</ulink>
- and oversees the &a.security-officer;.
- </para>
+ <ulink url="&url.base;/security/">FreeBSD Security
+ Officer</ulink> and oversees the
+ &a.security-officer;.</para>
</listitem>
</varlistentry>
@@ -2469,38 +2520,40 @@ ControlPersist yes</screen>
<term>&a.developers;</term>
<listitem>
- <para>All committers are subscribed to -developers. This list was created to be a
- forum for the committers <quote>community</quote> issues.
- Examples are Core
+ <para>All committers are subscribed to -developers. This
+ list was created to be a forum for the committers
+ <quote>community</quote> issues. Examples are Core
voting, announcements, etc.</para>
- <para>The &a.developers; is for the exclusive use of
- FreeBSD committers. In order to develop FreeBSD, committers must
- have the ability to openly discuss matters that will be resolved
- before they are publicly announced. Frank discussions of work in
- progress are not suitable for open publication and may harm FreeBSD.</para>
+ <para>The &a.developers; is for the exclusive use of FreeBSD
+ committers. In order to develop FreeBSD, committers must
+ have the ability to openly discuss matters that will be
+ resolved before they are publicly announced. Frank
+ discussions of work in progress are not suitable for open
+ publication and may harm FreeBSD.</para>
- <para>All FreeBSD committers are reminded to obey the copyright of the
- original author(s) of &a.developers; mail. Do not publish or
- forward messages from the &a.developers; outside the list
- membership without permission of all of the authors.</para>
+ <para>All FreeBSD committers are reminded to obey the
+ copyright of the original author(s) of &a.developers;
+ mail. Do not publish or forward messages from the
+ &a.developers; outside the list membership without
+ permission of all of the authors.</para>
- <para>Copyright violators will be removed from the &a.developers;,
- resulting in a suspension of commit privileges. Repeated or
- flagrant violations may result in permanent revocation of
- commit privileges.</para>
+ <para>Copyright violators will be removed from the
+ &a.developers;, resulting in a suspension of commit
+ privileges. Repeated or flagrant violations may result in
+ permanent revocation of commit privileges.</para>
- <para>This list is
- <emphasis>not</emphasis> intended as a place for code reviews or a
- replacement for the &a.arch;. In fact
- using it as such hurts the FreeBSD Project as it gives a sense of a
- closed list where general decisions affecting all of the FreeBSD
- using community are made without being <quote>open</quote>.
- Last, but not least <emphasis>never, never ever, email
- the &a.developers; and CC:/BCC: another FreeBSD list</emphasis>.
- Never, ever email another FreeBSD email list and CC:/BCC:
- the &a.developers;. Doing so can greatly diminish the benefits
- of this list.</para>
+ <para>This list is <emphasis>not</emphasis> intended as a
+ place for code reviews or a replacement for the &a.arch;.
+ In fact using it as such hurts the FreeBSD Project as it
+ gives a sense of a closed list where general decisions
+ affecting all of the FreeBSD using community are made
+ without being <quote>open</quote>. Last, but not least
+ <emphasis>never, never ever, email the &a.developers; and
+ CC:/BCC: another FreeBSD list</emphasis>. Never, ever
+ email another FreeBSD email list and CC:/BCC: the
+ &a.developers;. Doing so can greatly diminish the
+ benefits of this list.</para>
</listitem>
</varlistentry>
</variablelist>
@@ -2532,12 +2585,14 @@ ControlPersist yes</screen>
<step>
<para>Send your public key
(<filename><envar>$HOME</envar>/.ssh/id_dsa.pub</filename>
- or <filename><envar>$HOME</envar>/.ssh/id_rsa.pub</filename>)
+ or
+ <filename><envar>$HOME</envar>/.ssh/id_rsa.pub</filename>)
to the person setting you up as a committer so it can be put
- into the <filename><replaceable>yourlogin</replaceable></filename> file in
+ into the
+ <filename><replaceable>yourlogin</replaceable></filename>
+ file in
<filename class="directory">/etc/ssh-keys/</filename> on
- <hostid>freefall</hostid>.
- </para>
+ <hostid>freefall</hostid>.</para>
</step>
</procedure>
@@ -2552,32 +2607,32 @@ ControlPersist yes</screen>
freefall.FreeBSD.org ls /usr</command>.</para>
<para>For more information, see
- <filename role="package">security/openssh</filename>, &man.ssh.1;,
- &man.ssh-add.1;, &man.ssh-agent.1;, &man.ssh-keygen.1;, and
- &man.scp.1;.</para>
+ <filename role="package">security/openssh</filename>,
+ &man.ssh.1;, &man.ssh-add.1;, &man.ssh-agent.1;,
+ &man.ssh-keygen.1;, and &man.scp.1;.</para>
</sect1>
<sect1 id="coverity">
<title>&coverity.prevent; Availability for &os; Committers</title>
- <para>In January 2006, the &os; Foundation obtained a license for
- &coverity.prevent; from &coverity; Ltd. With this donation, all
- &os; developers can obtain access to <application>Coverity
- Prevent</application> analysis results of all &os; Project
- software.</para>
+ <para>In January 2006, the &os; Foundation obtained a license
+ for &coverity.prevent; from &coverity; Ltd. With this
+ donation, all &os; developers can obtain access to
+ <application>Coverity Prevent</application> analysis results of
+ all &os; Project software.</para>
- <para>&os; developers who are interested in obtaining access to the
- analysis results of the automated <application>Coverity
- Prevent</application> runs, can find out more by logging
- into <hostid>freefall</hostid> and reading the relevant bits of the
- files:</para>
+ <para>&os; developers who are interested in obtaining access to
+ the analysis results of the automated
+ <application>Coverity Prevent</application> runs, can find out
+ more by logging into <hostid>freefall</hostid> and reading the
+ relevant bits of the files:</para>
<variablelist>
<varlistentry>
<term><filename>/usr/local/coverity/coverity_license.txt</filename></term>
<listitem>
- <para>The license terms to which the &os; developers will have
- to agree in order to use &coverity.prevent; analysis
+ <para>The license terms to which the &os; developers will
+ have to agree in order to use &coverity.prevent; analysis
results.</para>
</listitem>
</varlistentry>
@@ -2585,39 +2640,45 @@ ControlPersist yes</screen>
<varlistentry>
<term><filename>/usr/local/coverity/coverity_announcement.txt</filename></term>
<listitem>
- <para>The announcement posted to the developers' mailing list of the
- &os; Project. It contains useful information about the &os;
- Foundation and &coverity; Ltd., as well as signup information
- for registering with the &coverity.prevent; installation of the
- &os; Cluster.</para>
+ <para>The announcement posted to the developers' mailing
+ list of the &os; Project. It contains useful information
+ about the &os; Foundation and &coverity; Ltd., as
+ well as signup information for registering with the
+ &coverity.prevent; installation of the &os;
+ Cluster.</para>
<para>After reading and understanding the license terms
- of <filename>coverity_license.txt</filename>, all &os; developers
- who are interested in using the analysis results of
- &coverity.prevent; should read this file.</para>
+ of <filename>coverity_license.txt</filename>, all &os;
+ developers who are interested in using the analysis
+ results of &coverity.prevent; should read this
+ file.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>/usr/local/coverity/coverity_readme.txt</filename></term>
<listitem>
- <para>A short guide about fixes which are committed to the &os;
- source tree after being detected by &coverity.prevent; and
- analyzed by a &os; developer.</para>
+ <para>A short guide about fixes which are committed to the
+ &os; source tree after being detected by
+ &coverity.prevent; and analyzed by a &os;
+ developer.</para>
</listitem>
</varlistentry>
</variablelist>
<para>The &os; Wiki includes a mini-guide for developers who are
- interested in working with the &coverity.prevent; analysis reports:
- <ulink url="http://wiki.freebsd.org/CoverityPrevent"></ulink>. Please
- note that this mini-guide is only readable by &os; developers, so if you
- cannot access this page, you will have to ask someone to add you to the
- appropriate Wiki access list.</para>
+ interested in working with the &coverity.prevent; analysis
+ reports:
+ <ulink url="http://wiki.freebsd.org/CoverityPrevent"></ulink>.
+ Please note that this mini-guide is only readable by &os;
+ developers, so if you cannot access this page, you will have to
+ ask someone to add you to the appropriate Wiki access
+ list.</para>
- <para>Finally, all &os; developers who are going to use &coverity.prevent;
- are always encouraged to ask for more details and usage information, by
- posting any questions to the mailing list of the &os; developers.</para>
+ <para>Finally, all &os; developers who are going to use
+ &coverity.prevent; are always encouraged to ask for more details
+ and usage information, by posting any questions to the mailing
+ list of the &os; developers.</para>
</sect1>
<sect1 id="rules">
@@ -2674,9 +2735,9 @@ ControlPersist yes</screen>
<listitem>
<para>Respect all code freezes and read the
- <literal>committers</literal> and <literal>developers</literal>
- mailing lists in a timely manner so you know when a code freeze is
- in effect.</para>
+ <literal>committers</literal> and
+ <literal>developers</literal> mailing lists in a timely
+ manner so you know when a code freeze is in effect.</para>
</listitem>
<listitem>
@@ -2699,41 +2760,40 @@ ControlPersist yes</screen>
<para>As noted, breaking some of these rules can be grounds for
suspension or, upon repeated offense, permanent removal of
- commit privileges. Individual members of core
- have the power to temporarily suspend commit privileges until
- core as a whole has the chance to review the
- issue. In case of an <quote>emergency</quote> (a committer
- doing damage to the repository), a temporary suspension may also
- be done by the repository meisters.
- Only a 2/3 majority of core
- has the authority to suspend commit privileges for longer
- than a week or to remove them permanently.
- This rule does not exist to set core up as a bunch
- of cruel dictators who can dispose of committers as casually as
- empty soda cans, but to give the project a kind of safety fuse.
- If someone is out of control, it is important to be
- able to deal with this immediately rather than be paralyzed by
- debate. In all cases, a committer whose privileges are
- suspended or revoked is entitled to a <quote>hearing</quote> by core,
- the total duration of the suspension being determined at that
- time. A committer whose privileges are suspended may also
- request a review of the decision after 30 days and every 30 days
- thereafter (unless the total suspension period is less than 30
- days). A committer whose privileges have been revoked entirely
- may request a review after a period of 6 months has elapsed.
- This review policy is <emphasis>strictly informal</emphasis>
- and, in all cases, core reserves the right to either act on or
- disregard requests for review if they feel their original
- decision to be the right one.</para>
+ commit privileges. Individual members of core have the power to
+ temporarily suspend commit privileges until core as a whole has
+ the chance to review the issue. In case of an
+ <quote>emergency</quote> (a committer doing damage to the
+ repository), a temporary suspension may also be done by the
+ repository meisters. Only a 2/3 majority of core has the
+ authority to suspend commit privileges for longer than a week or
+ to remove them permanently. This rule does not exist to set
+ core up as a bunch of cruel dictators who can dispose of
+ committers as casually as empty soda cans, but to give the
+ project a kind of safety fuse. If someone is out of control, it
+ is important to be able to deal with this immediately rather
+ than be paralyzed by debate. In all cases, a committer whose
+ privileges are suspended or revoked is entitled to a
+ <quote>hearing</quote> by core, the total duration of the
+ suspension being determined at that time. A committer whose
+ privileges are suspended may also request a review of the
+ decision after 30 days and every 30 days thereafter (unless the
+ total suspension period is less than 30 days). A committer
+ whose privileges have been revoked entirely may request a review
+ after a period of 6 months has elapsed. This review policy is
+ <emphasis>strictly informal</emphasis> and, in all cases, core
+ reserves the right to either act on or disregard requests for
+ review if they feel their original decision to be the right
+ one.</para>
<para>In all other aspects of project operation, core is a subset
- of committers and is bound by the <emphasis>same
- rules</emphasis>. Just because someone is in core this does not mean
- that they have special dispensation to step outside any of
- the lines painted here; core's <quote>special powers</quote>
- only kick in when it acts as a group, not on an individual
- basis. As individuals, the core team members are all committers
- first and core second.</para>
+ of committers and is bound by the
+ <emphasis>same rules</emphasis>. Just because someone is in
+ core this does not mean that they have special dispensation to
+ step outside any of the lines painted here; core's
+ <quote>special powers</quote> only kick in when it acts as a
+ group, not on an individual basis. As individuals, the core
+ team members are all committers first and core second.</para>
<sect2>
<title>Details</title>
@@ -2744,25 +2804,26 @@ ControlPersist yes</screen>
<para>This means that you need to treat other committers as
the peer-group developers that they are. Despite our
- occasional attempts to prove the contrary, one does not get
- to be a committer by being stupid and nothing rankles more
- than being treated that way by one of your peers. Whether
- we always feel respect for one another or not (and
+ occasional attempts to prove the contrary, one does not
+ get to be a committer by being stupid and nothing rankles
+ more than being treated that way by one of your peers.
+ Whether we always feel respect for one another or not (and
everyone has off days), we still have to
<emphasis>treat</emphasis> other committers with respect
- at all times, on public forums and in private email.</para>
+ at all times, on public forums and in private
+ email.</para>
- <para>Being able to work together long term is this project's
- greatest asset, one far more important than any set of
- changes to the code, and turning arguments about code into
- issues that affect our long-term ability to work
+ <para>Being able to work together long term is this
+ project's greatest asset, one far more important than any
+ set of changes to the code, and turning arguments about
+ code into issues that affect our long-term ability to work
harmoniously together is just not worth the trade-off by
any conceivable stretch of the imagination.</para>
- <para>To comply with this rule, do not send email when you are
- angry or otherwise behave in a manner which is likely to
- strike others as needlessly confrontational. First calm
- down, then think about how to communicate in the most
+ <para>To comply with this rule, do not send email when you
+ are angry or otherwise behave in a manner which is likely
+ to strike others as needlessly confrontational. First
+ calm down, then think about how to communicate in the most
effective fashion for convincing the other person(s) that
your side of the argument is correct, do not just blow off
some steam so you can feel better in the short term at the
@@ -2771,36 +2832,37 @@ ControlPersist yes</screen>
public aggression which impair our ability to work well
together will be dealt with severely by the project
leadership and may result in suspension or termination of
- your commit privileges. The project leadership will
- take into account both public and private communications
+ your commit privileges. The project leadership will take
+ into account both public and private communications
brought before it. It will not seek the disclosure of
private communications, but it will take it into account
if it is volunteered by the committers involved in the
complaint.</para>
- <para>All of this is never an option which the
- project's leadership enjoys in the slightest, but unity
- comes first. No amount of code or good advice is worth
- trading that away.</para>
+ <para>All of this is never an option which the project's
+ leadership enjoys in the slightest, but unity comes first.
+ No amount of code or good advice is worth trading that
+ away.</para>
</listitem>
<listitem>
<para>Respect other contributors.</para>
- <para>You were not always a committer. At one time you were
- a contributor. Remember that at all times. Remember what
- it was like trying to get help and attention. Do not forget
- that your work as a contributor was very important to
- you. Remember what it was like. Do not discourage, belittle,
- or demean contributors. Treat them with respect. They are
- our committers in waiting. They are every bit as important
- to the project as committers. Their contributions are as
- valid and as important as your own. After all, you made
- many contributions before you became a committer. Always
- remember that. </para>
+ <para>You were not always a committer. At one time you were
+ a contributor. Remember that at all times. Remember what
+ it was like trying to get help and attention. Do not
+ forget that your work as a contributor was very important
+ to you. Remember what it was like. Do not discourage,
+ belittle, or demean contributors. Treat them with
+ respect. They are our committers in waiting. They are
+ every bit as important to the project as committers.
+ Their contributions are as valid and as important as your
+ own. After all, you made many contributions before you
+ became a committer. Always remember that.</para>
- <para>Consider the points raised under <xref linkend="respect"/>
- and apply them also to contributors.</para>
+ <para>Consider the points raised under
+ <xref linkend="respect"/> and apply them also to
+ contributors.</para>
</listitem>
<listitem>
@@ -2809,19 +2871,19 @@ ControlPersist yes</screen>
<para>The repository is not where changes should be
initially submitted for correctness or argued over, that
- should happen first in the mailing lists and the commit should
- only happen once something resembling consensus has
+ should happen first in the mailing lists and the commit
+ should only happen once something resembling consensus has
been reached. This does not mean that you have to ask
permission before correcting every obvious syntax error or
manual page misspelling, simply that you should try to
- develop a feel for when a proposed change is not quite such
- a no-brainer and requires some feedback first. People
- really do not mind sweeping changes if the result is
- something clearly better than what they had before, they
- just do not like being <emphasis>surprized</emphasis> by
- those changes. The very best way of making sure that
- you are on the right track is to have your code reviewed by
- one or more other committers.</para>
+ develop a feel for when a proposed change is not quite
+ such a no-brainer and requires some feedback first.
+ People really do not mind sweeping changes if the result
+ is something clearly better than what they had before,
+ they just do not like being <emphasis>surprized</emphasis>
+ by those changes. The very best way of making sure that
+ you are on the right track is to have your code reviewed
+ by one or more other committers.</para>
<para>When in doubt, ask for review!</para>
</listitem>
@@ -2837,23 +2899,21 @@ ControlPersist yes</screen>
<filename>Makefile</filename> for any package or subtree
which is being actively maintained by one or more people;
see <ulink
- url="&url.books.developers-handbook;/policies.html">
- http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/policies.html</ulink>
+ url="&url.books.developers-handbook;/policies.html">http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/policies.html</ulink>
for documentation on this. Where sections of code have
several maintainers, commits to affected areas by one
maintainer need to be reviewed by at least one other
maintainer. In cases where the
<quote>maintainer-ship</quote> of something is not clear,
- you can also look at the repository logs for the file(s) in
- question and see if someone has been working recently or
- predominantly in that area.</para>
+ you can also look at the repository logs for the file(s)
+ in question and see if someone has been working recently
+ or predominantly in that area.</para>
<para>Other areas of FreeBSD fall under the control of
someone who manages an overall category of FreeBSD
evolution, such as internationalization or networking.
See <ulink
- url="&url.base;/administration.html">
- http://www.FreeBSD.org/administration.html</ulink>
+ url="&url.base;/administration.html">http://www.FreeBSD.org/administration.html</ulink>
for more information on this.</para>
</listitem>
@@ -2866,59 +2926,56 @@ ControlPersist yes</screen>
<para>This may be hard to swallow in times of conflict (when
each side is convinced that they are in the right, of
- course) but a version control system makes it unnecessary to have an ongoing
- dispute raging when it is far easier to simply reverse the
- disputed change, get everyone calmed down again and then
- try to figure out what is the best way to proceed. If the change
- turns out to be the best thing after all, it can be easily
- brought back. If it turns out not to be, then the users
- did not have to live with the bogus change in the tree
- while everyone was busily debating its merits. People
- <emphasis>very</emphasis> rarely call for back-outs in the repository
- since discussion generally exposes bad or controversial
- changes before the commit even happens, but on such rare
- occasions the back-out should be done without argument so
- that we can get immediately on to the topic of figuring
- out whether it was bogus or not.</para>
+ course) but a version control system makes it unnecessary
+ to have an ongoing dispute raging when it is far easier to
+ simply reverse the disputed change, get everyone calmed
+ down again and then try to figure out what is the best way
+ to proceed. If the change turns out to be the best thing
+ after all, it can be easily brought back. If it turns out
+ not to be, then the users did not have to live with the
+ bogus change in the tree while everyone was busily
+ debating its merits. People <emphasis>very</emphasis>
+ rarely call for back-outs in the repository since
+ discussion generally exposes bad or controversial changes
+ before the commit even happens, but on such rare occasions
+ the back-out should be done without argument so that we
+ can get immediately on to the topic of figuring out
+ whether it was bogus or not.</para>
</listitem>
<listitem>
- <para>Changes go to &os.current; before
- &os.stable; unless specifically permitted
- by the release engineer or unless they are not applicable
- to &os.current;. Any non-trivial or
- non-urgent change which is applicable should also be
- allowed to sit in &os.current; for at least
- 3 days before merging so that it can be given sufficient
- testing. The release engineer has the same authority over
- the &os.stable; branch as outlined in rule
- #5.</para>
+ <para>Changes go to &os.current; before &os.stable; unless
+ specifically permitted by the release engineer or unless
+ they are not applicable to &os.current;. Any non-trivial
+ or non-urgent change which is applicable should also be
+ allowed to sit in &os.current; for at least 3 days before
+ merging so that it can be given sufficient testing. The
+ release engineer has the same authority over the
+ &os.stable; branch as outlined in rule #5.</para>
<para>This is another <quote>do not argue about it</quote>
issue since it is the release engineer who is ultimately
responsible (and gets beaten up) if a change turns out to
be bad. Please respect this and give the release engineer
- your full cooperation when it comes to the
- &os.stable; branch. The management of
- &os.stable; may frequently seem to be
- overly conservative to the casual observer, but also bear
- in mind the fact that conservatism is supposed to be the
- hallmark of &os.stable; and different rules
- apply there than in &os.current;. There is
- also really no point in having &os.current;
- be a testing ground if changes are merged over to
- &os.stable; immediately. Changes need a
- chance to be tested by the &os.current;
- developers, so allow some time to elapse before merging
- unless the &os.stable; fix is critical,
- time sensitive or so obvious as to make further testing
- unnecessary (spelling fixes to manual pages, obvious bug/typo
- fixes, etc.) In other words, apply common sense.</para>
+ your full cooperation when it comes to the &os.stable;
+ branch. The management of &os.stable; may frequently seem
+ to be overly conservative to the casual observer, but also
+ bear in mind the fact that conservatism is supposed to be
+ the hallmark of &os.stable; and different rules apply
+ there than in &os.current;. There is also really no point
+ in having &os.current; be a testing ground if changes are
+ merged over to &os.stable; immediately. Changes need a
+ chance to be tested by the &os.current; developers, so
+ allow some time to elapse before merging unless the
+ &os.stable; fix is critical, time sensitive or so obvious
+ as to make further testing unnecessary (spelling fixes to
+ manual pages, obvious bug/typo fixes, etc.) In other
+ words, apply common sense.</para>
- <para>Changes to the security branches
- (for example, <literal>RELENG_7_0</literal>) must be
- approved by a member of the &a.security-officer;, or in
- some cases, by a member of the &a.re;.</para>
+ <para>Changes to the security branches (for example,
+ <literal>RELENG_7_0</literal>) must be approved by a
+ member of the &a.security-officer;, or in some cases, by a
+ member of the &a.re;.</para>
</listitem>
<listitem>
@@ -2931,42 +2988,43 @@ ControlPersist yes</screen>
to continue to attract new members. There will be
occasions when, despite everyone's very best attempts at
self-control, tempers are lost and angry words are
- exchanged. The best thing that can be done in such cases is to minimize
- the effects of this until everyone has cooled back down. That
- means that you should not air your angry words in public
- and you should not forward private correspondence to
- public mailing lists or aliases. What people say
- one-to-one is often much less sugar-coated than what they
- would say in public, and such communications therefore
- have no place there - they only serve to inflame an
- already bad situation. If the person sending you a
+ exchanged. The best thing that can be done in such cases
+ is to minimize the effects of this until everyone has
+ cooled back down. That means that you should not air your
+ angry words in public and you should not forward private
+ correspondence to public mailing lists or aliases. What
+ people say one-to-one is often much less sugar-coated than
+ what they would say in public, and such communications
+ therefore have no place there - they only serve to inflame
+ an already bad situation. If the person sending you a
flame-o-gram at least had the grace to send it privately,
then have the grace to keep it private yourself. If you
feel you are being unfairly treated by another developer,
and it is causing you anguish, bring the matter up with
- core rather than taking it public. Core will do its best to
- play peace makers and get things back to sanity. In cases
- where the dispute involves a change to the codebase and
- the participants do not appear to be reaching an amicable
- agreement, core may appoint a mutually-agreeable 3rd party
- to resolve the dispute. All parties involved must then
- agree to be bound by the decision reached by this 3rd
- party.</para>
+ core rather than taking it public. Core will do its best
+ to play peace makers and get things back to sanity. In
+ cases where the dispute involves a change to the codebase
+ and the participants do not appear to be reaching an
+ amicable agreement, core may appoint a mutually-agreeable
+ 3rd party to resolve the dispute. All parties involved
+ must then agree to be bound by the decision reached by
+ this 3rd party.</para>
</listitem>
<listitem>
<para>Respect all code freezes and read the
- <literal>committers</literal> and <literal>developers</literal>
- mailing list on a timely basis so you know when a code freeze is
- in effect.</para>
+ <literal>committers</literal> and
+ <literal>developers</literal> mailing list on a timely
+ basis so you know when a code freeze is in effect.</para>
- <para>Committing unapproved changes during a code freeze is a really
- big mistake and committers are expected to keep up-to-date
- on what is going on before jumping in after a long absence
- and committing 10 megabytes worth of accumulated stuff.
- People who abuse this on a regular basis will have their
- commit privileges suspended until they get back from the
- FreeBSD Happy Reeducation Camp we run in Greenland.</para>
+ <para>Committing unapproved changes during a code freeze is
+ a really big mistake and committers are expected to keep
+ up-to-date on what is going on before jumping in after a
+ long absence and committing 10 megabytes worth of
+ accumulated stuff. People who abuse this on a regular
+ basis will have their commit privileges suspended until
+ they get back from the FreeBSD Happy Reeducation Camp we
+ run in Greenland.</para>
</listitem>
<listitem>
@@ -2977,10 +3035,11 @@ ControlPersist yes</screen>
something. If you have not done it before, chances are
good that you do not actually know the way we do things
and really need to ask first or you are going to
- completely embarrass yourself in public. There is no shame
- in asking <quote>how in the heck do I do this?</quote> We
- already know you are an intelligent person; otherwise, you
- would not be a committer.</para>
+ completely embarrass yourself in public. There is no
+ shame in asking
+ <quote>how in the heck do I do this?</quote> We already
+ know you are an intelligent person; otherwise, you would
+ not be a committer.</para>
</listitem>
<listitem>
@@ -3015,24 +3074,25 @@ ControlPersist yes</screen>
maintainer(s).</para>
<para>The trees mentioned above are for contributed software
- usually imported onto a vendor branch. Committing something
- there, even if it does not take the file off the vendor branch,
- may cause unnecessary headaches for those responsible for
- maintaining that particular piece of software. Thus, unless
- you have <emphasis>explicit</emphasis> approval from the
- maintainer (or you are the maintainer), do
- <emphasis>not</emphasis> commit there!</para>
+ usually imported onto a vendor branch. Committing
+ something there, even if it does not take the file off the
+ vendor branch, may cause unnecessary headaches for those
+ responsible for maintaining that particular piece of
+ software. Thus, unless you have
+ <emphasis>explicit</emphasis> approval from the maintainer
+ (or you are the maintainer), do <emphasis>not</emphasis>
+ commit there!</para>
- <para>Please note that this does not mean you should not try to
- improve the software in question; you are still more than
- welcome to do so. Ideally, you should submit your patches to
- the vendor. If your changes are FreeBSD-specific, talk to the
- maintainer; they may be willing to apply them locally. But
- whatever you do, do <emphasis>not</emphasis> commit there by
- yourself!</para>
+ <para>Please note that this does not mean you should not try
+ to improve the software in question; you are still more
+ than welcome to do so. Ideally, you should submit your
+ patches to the vendor. If your changes are
+ FreeBSD-specific, talk to the maintainer; they may be
+ willing to apply them locally. But whatever you do, do
+ <emphasis>not</emphasis> commit there by yourself!</para>
- <para>Contact the &a.core; if you wish to take up maintainership
- of an unmaintained part of the tree.</para>
+ <para>Contact the &a.core; if you wish to take up
+ maintainership of an unmaintained part of the tree.</para>
</listitem>
</orderedlist>
</sect2>
@@ -3040,31 +3100,31 @@ ControlPersist yes</screen>
<sect2>
<title>Policy on Multiple Architectures</title>
- <para>FreeBSD has added several new architecture ports during recent
- release cycles and is truly no longer an &i386; centric operating
- system. In an effort to make it easier to keep FreeBSD portable
- across the platforms we support, core has developed the following
- mandate:</para>
+ <para>FreeBSD has added several new architecture ports during
+ recent release cycles and is truly no longer an &i386; centric
+ operating system. In an effort to make it easier to keep
+ FreeBSD portable across the platforms we support, core has
+ developed the following mandate:</para>
- <blockquote>
- <para>Our 32-bit reference platform is &arch.i386;, and our 64-bit
- reference platform is &arch.sparc64;. Major design work (including
- major API and ABI changes) must prove itself on at least one
- 32-bit and at least one 64-bit platform, preferably the
- primary reference platforms, before it may be committed
- to the source tree.</para>
- </blockquote>
+ <blockquote>
+ <para>Our 32-bit reference platform is &arch.i386;, and our
+ 64-bit reference platform is &arch.sparc64;. Major design
+ work (including major API and ABI changes) must prove
+ itself on at least one 32-bit and at least one 64-bit
+ platform, preferably the primary reference platforms,
+ before it may be committed to the source tree.</para>
+ </blockquote>
- <para>The &arch.i386; and &arch.sparc64; platforms were chosen due to being more
- readily available to developers and as representatives of more
- diverse processor and system designs - big versus little endian,
- register file versus register stack, different DMA and cache
- implementations, hardware page tables versus software TLB management
- etc.</para>
+ <para>The &arch.i386; and &arch.sparc64; platforms were chosen
+ due to being more readily available to developers and as
+ representatives of more diverse processor and system designs -
+ big versus little endian, register file versus register stack,
+ different DMA and cache implementations, hardware page tables
+ versus software TLB management etc.</para>
- <para>The &arch.ia64; platform has many of the same complications that
- &arch.sparc64; has, but is still limited in availability to
- developers.</para>
+ <para>The &arch.ia64; platform has many of the same
+ complications that &arch.sparc64; has, but is still limited in
+ availability to developers.</para>
<para>We will continue to re-evaluate this policy as cost and
availability of the 64-bit platforms change.</para>
@@ -3140,35 +3200,35 @@ ControlPersist yes</screen>
<para>FreeBSD is a highly portable operating system intended to
function on many different types of hardware architectures.
- Maintaining clean separation of Machine Dependent (MD) and Machine
- Independent (MI) code, as well as minimizing MD code, is an important
- part of our strategy to remain agile with regards to current
- hardware trends. Each new hardware architecture supported by
- FreeBSD adds substantially to the cost of code maintenance,
- toolchain support, and release engineering. It also dramatically
- increases the cost of effective testing of kernel changes. As such,
- there is strong motivation to differentiate between classes of
- support for various architectures while remaining strong in a few
- key architectures that are seen as the FreeBSD "target audience".
- </para>
+ Maintaining clean separation of Machine Dependent (MD) and
+ Machine Independent (MI) code, as well as minimizing MD code, is
+ an important part of our strategy to remain agile with regards
+ to current hardware trends. Each new hardware architecture
+ supported by FreeBSD adds substantially to the cost of code
+ maintenance, toolchain support, and release engineering. It
+ also dramatically increases the cost of effective testing of
+ kernel changes. As such, there is strong motivation to
+ differentiate between classes of support for various
+ architectures while remaining strong in a few key architectures
+ that are seen as the FreeBSD "target audience".</para>
<sect2>
<title>Statement of General Intent</title>
<para>The FreeBSD Project targets "production quality commercial
- off-the-shelf (COTS) workstation, server, and high-end embedded
- systems". By retaining a focus on a narrow set of architectures
- of interest in these environments, the FreeBSD Project is able
- to maintain high levels of quality, stability, and performance,
- as well as minimize the load on various support teams on the
- project, such as the ports team, documentation team,
- security officer, and release engineering teams. Diversity in
- hardware support broadens the options for FreeBSD consumers by
- offering new features and usage opportunities (such as support
- for 64-bit CPUs, use in embedded environments, etc.), but these
- benefits must always be carefully considered in terms of the real-world
- maintenance cost associated with additional platform support.
- </para>
+ off-the-shelf (COTS) workstation, server, and high-end
+ embedded systems". By retaining a focus on a narrow set of
+ architectures of interest in these environments, the FreeBSD
+ Project is able to maintain high levels of quality, stability,
+ and performance, as well as minimize the load on various
+ support teams on the project, such as the ports team,
+ documentation team, security officer, and release engineering
+ teams. Diversity in hardware support broadens the options for
+ FreeBSD consumers by offering new features and usage
+ opportunities (such as support for 64-bit CPUs, use in
+ embedded environments, etc.), but these benefits must always
+ be carefully considered in terms of the real-world maintenance
+ cost associated with additional platform support.</para>
<para>The FreeBSD Project differentiates platform targets into
four tiers. Each tier includes a specification of the
@@ -3188,42 +3248,43 @@ ControlPersist yes</screen>
functional across all Tier 1 architectures for every release
(features which are inherently architecture-specific, such as
support for hardware device drivers, may be exempt from this
- requirement). In general, all Tier 1 platforms must have build
- and Tinderbox support either in the FreeBSD.org cluster, or be
- easily available for all developers. Embedded platforms may
- substitute an emulator available in the FreeBSD cluster for
- actual hardware.</para>
+ requirement). In general, all Tier 1 platforms must have
+ build and Tinderbox support either in the FreeBSD.org cluster,
+ or be easily available for all developers. Embedded platforms
+ may substitute an emulator available in the FreeBSD cluster
+ for actual hardware.</para>
<para>Tier 1 architectures are expected to be Production Quality
with respects to all aspects of the FreeBSD operating system,
including installation and development environments.</para>
<para>Tier 1 architectures are expected to be completely
- integrated into the source tree and have all features
+ integrated into the source tree and have all features
necessary to produce an entire system relevant for that target
- architecture. Tier 1 architectures generally have at least 6 active
- developers.</para>
+ architecture. Tier 1 architectures generally have at least 6
+ active developers.</para>
<para>Tier 1 architectures are expected to be fully supported by
- the ports system. All the ports should build on a Tier 1
- platform, or have the appropriate filters to prevent the
- inappropriate ones from building there. The packaging system
- must support all Tier 1 architectures. To ensure an
- architecture's Tier 1 status, proponents of that architecture
- must show that all relevant packages can be built on that
- platform.</para>
+ the ports system. All the ports should build on a Tier 1
+ platform, or have the appropriate filters to prevent the
+ inappropriate ones from building there. The packaging system
+ must support all Tier 1 architectures. To ensure an
+ architecture's Tier 1 status, proponents of that architecture
+ must show that all relevant packages can be built on that
+ platform.</para>
<para>Tier 1 embedded architectures must be able to cross-build
- packages on at least one other Tier 1 architecture. The
- packages must be the most relevant for the platform, but may
- be a non-empty subset of those that build natively.</para>
+ packages on at least one other Tier 1 architecture. The
+ packages must be the most relevant for the platform, but may
+ be a non-empty subset of those that build natively.</para>
<para>Tier 1 architectures must be fully documented. All basic
- operations need to be covered by the handbook or other
- documents. All relevant integration documentation must also
- be integrated into the tree, or readily available.</para>
+ operations need to be covered by the handbook or other
+ documents. All relevant integration documentation must also
+ be integrated into the tree, or readily available.</para>
- <para>Current Tier 1 platforms are &arch.i386; and &arch.amd64;.</para>
+ <para>Current Tier 1 platforms are &arch.i386; and
+ &arch.amd64;.</para>
</sect2>
<sect2>
@@ -3235,47 +3296,50 @@ ControlPersist yes</screen>
maintainer is expected to work with the platform maintainers
to refine these changes. Major new toolchain components are
allowed to break support for Tier 2 architectures if the
- FreeBSD-local changes have not been incorporated upstream. The
- toolchain maintainers are expected to provide prompt review of
- any proposed changes and cannot block, through their inaction,
- changes going into the tree. New features added to FreeBSD
- should be feasible to implement on these platforms, but an
- implementation is not required before the feature may be added
- to the FreeBSD source tree. New features that may be difficult
- to implement on Tier 2 architectures should provide a means of
- disabling them on those architectures. The implementation of
- a Tier 2 architecture may be committed to the main FreeBSD
- tree as long as it does not interfere with production work on
- Tier 1 platforms, or substantially with other Tier 2 platforms.
- Before a Tier 2 platform can be added to the FreeBSD base
- source tree, the platform must be able to boot multi-user on
- actual hardware. Generally, there must be at least three active
- developers working on the platform.</para>
+ FreeBSD-local changes have not been incorporated upstream.
+ The toolchain maintainers are expected to provide prompt
+ review of any proposed changes and cannot block, through their
+ inaction, changes going into the tree. New features added to
+ FreeBSD should be feasible to implement on these platforms,
+ but an implementation is not required before the feature may
+ be added to the FreeBSD source tree. New features that may be
+ difficult to implement on Tier 2 architectures should provide
+ a means of disabling them on those architectures. The
+ implementation of a Tier 2 architecture may be committed to
+ the main FreeBSD tree as long as it does not interfere with
+ production work on Tier 1 platforms, or substantially with
+ other Tier 2 platforms. Before a Tier 2 platform can be added
+ to the FreeBSD base source tree, the platform must be able to
+ boot multi-user on actual hardware. Generally, there must be
+ at least three active developers working on the
+ platform.</para>
- <para>Tier 2 architectures are usually systems targeted at Tier 1
- support, but that are still under development. Architectures
- reaching end of life may also be moved from Tier 1 status to Tier
- 2 status as the availability of resources to continue to maintain
- the system in a Production Quality state diminishes. Well supported
- niche architectures may also be Tier 2.</para>
+ <para>Tier 2 architectures are usually systems targeted at Tier
+ 1 support, but that are still under development.
+ Architectures reaching end of life may also be moved from Tier
+ 1 status to Tier 2 status as the availability of resources to
+ continue to maintain the system in a Production Quality state
+ diminishes. Well supported niche architectures may also be
+ Tier 2.</para>
<para>Tier 2 architectures may have some support for them
- integrated into the ports infrastructure. They may have cross
- compilation support added, at the discretion of portmgr. Some
- ports must built natively into packages if the package system
- supports that architecture. If not integrated into the base
- system, some external patches for the architecture for ports
- must be available.</para>
+ integrated into the ports infrastructure. They may have cross
+ compilation support added, at the discretion of portmgr. Some
+ ports must built natively into packages if the package system
+ supports that architecture. If not integrated into the base
+ system, some external patches for the architecture for ports
+ must be available.</para>
<para>Tier 2 architectures can be integrated into the FreeBSD
- handbook. The basics for how to get a system running must be
- documented, although not necessarily for every single board or
- system a Tier 2 architecture supports. The supported hardware
- list must exist and should be no more than a couple of months
- old. It should be integrated into the FreeBSD
- documentation.</para>
+ handbook. The basics for how to get a system running must be
+ documented, although not necessarily for every single board or
+ system a Tier 2 architecture supports. The supported hardware
+ list must exist and should be no more than a couple of months
+ old. It should be integrated into the FreeBSD
+ documentation.</para>
- <para>Current Tier 2 platforms are &arch.arm;, &arch.ia64;, &arch.pc98;, &arch.powerpc;, and &arch.sparc64;.</para>
+ <para>Current Tier 2 platforms are &arch.arm;, &arch.ia64;,
+ &arch.pc98;, &arch.powerpc;, and &arch.sparc64;.</para>
</sect2>
<sect2>
@@ -3297,21 +3361,22 @@ ControlPersist yes</screen>
engineer.</para>
<para>Tier 3 platforms may have ports support, either integrated
- or external, but do not require it.</para>
+ or external, but do not require it.</para>
<para>Tier 3 platforms must have the basics documented for how
- to build a kernel and how to boot it on at least one target
- hardware or emulation environment. This documentation need
- not be integrated into the FreeBSD tree.</para>
+ to build a kernel and how to boot it on at least one target
+ hardware or emulation environment. This documentation need
+ not be integrated into the FreeBSD tree.</para>
- <para>Current Tier 3 platforms are &arch.mips; and &s390;.</para>
+ <para>Current Tier 3 platforms are &arch.mips; and
+ &s390;.</para>
</sect2>
<sect2>
<title>Tier 4: Unsupported Architectures</title>
- <para>Tier 4 systems are not supported in any form by the project.
- </para>
+ <para>Tier 4 systems are not supported in any form by the
+ project.</para>
<para>All systems not otherwise classified into a support tier
are Tier 4 systems.</para>
@@ -3344,16 +3409,16 @@ ControlPersist yes</screen>
copies.</para>
<para>The easiest way to add a new port is to use the
- <command>addport</command> script from your machine (located
- in the <filename>ports/Tools/scripts</filename> directory).
- It will add a port from the
- directory you specify, determining the category automatically
- from the port <filename>Makefile</filename>.
- It will also add an entry to the port's
- category <filename>Makefile</filename>. It was
- written by &a.mharo;, &a.will;, and &a.garga;. When sending
- questions about this script to the &a.ports;, please also CC
- &a.crees;, the current maintainer.</para>
+ <command>addport</command> script from your machine
+ (located in the <filename>ports/Tools/scripts</filename>
+ directory). It will add a port from the directory you
+ specify, determining the category automatically from the
+ port <filename>Makefile</filename>. It will also add an
+ entry to the port's category
+ <filename>Makefile</filename>. It was written by
+ &a.mharo;, &a.will;, and &a.garga;. When sending
+ questions about this script to the &a.ports;, please
+ also CC &a.crees;, the current maintainer.</para>
</answer>
</qandaentry>
@@ -3374,29 +3439,29 @@ ControlPersist yes</screen>
&prompt.root; <userinput>pkg_add <replaceable>package you built above</replaceable></userinput>
&prompt.root; <userinput>make deinstall</userinput>
&prompt.root; <userinput>make reinstall</userinput>
-&prompt.root; <userinput>make package</userinput>
- </screen>
+&prompt.root; <userinput>make package</userinput></screen>
- <para>The
- <ulink url="&url.books.porters-handbook;/index.html">Porters
- Handbook</ulink> contains more detailed
+ <para>The <ulink
+ url="&url.books.porters-handbook;/index.html">Porters
+ Handbook</ulink> contains more detailed
instructions.</para>
- <para>Use &man.portlint.1; to check the syntax of the port.
- You do not necessarily have to eliminate all warnings but
- make sure you have fixed the simple ones.</para>
+ <para>Use &man.portlint.1; to check the syntax of the
+ port. You do not necessarily have to eliminate all
+ warnings but make sure you have fixed the simple
+ ones.</para>
<para>If the port came from a submitter who has not
contributed to the Project before, add that person's
name to the <ulink
- url="&url.articles.contributors;/contrib-additional.html">Additional
- Contributors</ulink> section of the FreeBSD Contributors
- List.</para>
+ url="&url.articles.contributors;/contrib-additional.html">Additional
+ Contributors</ulink> section of the FreeBSD
+ Contributors List.</para>
<para>Close the PR if the port came in as a PR. To close
- a PR, just do
- <userinput>edit-pr <replaceable>PR#</replaceable></userinput>
- on <hostid>freefall</hostid> and change the
+ a PR, just do <userinput>edit-pr
+ <replaceable>PR#</replaceable></userinput> on
+ <hostid>freefall</hostid> and change the
<varname>state</varname> from <constant>open</constant>
to <constant>closed</constant>. You will be asked to
enter a log message and then you are done.</para>
@@ -3414,55 +3479,63 @@ ControlPersist yes</screen>
<answer>
<para>First, please read the section about repository
- copies. Before you remove the port, you have to verify
+ copies. Before you remove the port, you have to verify
there are no other ports depending on it.</para>
+
<itemizedlist>
- <listitem>
- <para>Make sure there is no dependency on the port
- in the ports collection:</para>
- <itemizedlist>
- <listitem>
- <para>The port's PKGNAME should appear in exactly one
- line in a recent INDEX file.</para>
- </listitem>
- <listitem>
- <para>No other ports should contain any reference to
- the port's directory or PKGNAME in their
- Makefiles</para>
- </listitem>
- </itemizedlist>
- </listitem>
- <listitem>
- <para>Then, remove the port:</para>
+ <listitem>
+ <para>Make sure there is no dependency on the port
+ in the ports collection:</para>
- <procedure>
- <step>
- <para>Remove the port's files via <command>svn remove</command>.</para>
- </step>
+ <itemizedlist>
+ <listitem>
+ <para>The port's PKGNAME should appear in exactly
+ one line in a recent INDEX file.</para>
+ </listitem>
- <step>
- <para>Remove the <makevar>SUBDIR</makevar> listing of the port
- in the parent directory <filename>Makefile</filename>.</para>
- </step>
+ <listitem>
+ <para>No other ports should contain any reference
+ to the port's directory or PKGNAME in their
+ Makefiles</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
- <step>
- <para>Add an entry to
- <filename>ports/MOVED</filename>.</para>
- </step>
+ <listitem>
+ <para>Then, remove the port:</para>
- <step>
- <para>Remove the port from
- <filename>ports/LEGAL</filename> if it is there.</para>
- </step>
- </procedure>
+ <procedure>
+ <step>
+ <para>Remove the port's files via
+ <command>svn remove</command>.</para>
+ </step>
+
+ <step>
+ <para>Remove the <makevar>SUBDIR</makevar> listing
+ of the port in the parent directory
+ <filename>Makefile</filename>.</para>
+ </step>
+
+ <step>
+ <para>Add an entry to
+ <filename>ports/MOVED</filename>.</para>
+ </step>
+
+ <step>
+ <para>Remove the port from
+ <filename>ports/LEGAL</filename> if it is
+ there.</para>
+ </step>
+ </procedure>
</listitem>
</itemizedlist>
- <para>Alternatively, you can use the <command>rmport</command>
- script, from <filename class="directory">ports/Tools/scripts</filename>.
- This script was written by &a.vd;. When sending
- questions about this script to the &a.ports;, please also CC
- &a.crees;, the current maintainer.</para>
+ <para>Alternatively, you can use the
+ <command>rmport</command> script, from <filename
+ class="directory">ports/Tools/scripts</filename>.
+ This script was written by &a.vd;. When sending
+ questions about this script to the &a.ports;, please
+ also CC &a.crees;, the current maintainer.</para>
</answer>
</qandaentry>
</qandadiv>
@@ -3476,11 +3549,14 @@ ControlPersist yes</screen>
</question>
<answer>
- <para>This is essentially the reverse of deleting a port.</para>
+ <para>This is essentially the reverse of deleting a
+ port.</para>
+
<procedure>
- <step>
- <para>Figure out when the port was removed. Use this
- <ulink url="http://people.freebsd.org/~crees/removed_ports/index.xml">list</ulink>
+ <step>
+ <para>Figure out when the port was removed. Use this
+ <ulink
+ url="http://people.freebsd.org/~crees/removed_ports/index.xml">list</ulink>
and then copy the last living revision of the port:
<screen>&prompt.user; <userinput>cd /usr/ports/<replaceable>category
@@ -3488,43 +3564,47 @@ ControlPersist yes</screen>
&prompt.user; <userinput>svn cp 'svn+ssh://svn.freebsd.org/ports/<replaceable>category</replaceable>/<replaceable>portname</replaceable>/@{<replaceable>YYYY-MM-DD</replaceable>}' <replaceable>portname</replaceable>
</userinput></screen>
- Pick a date that is before the removal but after the last true
- commit.</para>
- </step>
-
- <step>
- <para>Perform whatever changes are necessary to make the port
- work again. If it was deleted because the distfiles are
- no longer available you will need to volunteer to host them
- yourself, or find someone else to do so.</para>
- </step>
-
- <step>
- <para><command>svn add</command> or <command>svn remove</command>
- any appropriate files.</para>
- </step>
-
- <step>
- <para>Restore the <makevar>SUBDIR</makevar> listing of the port
- in the parent directory <filename>Makefile</filename>, and
- delete the entry from <filename>ports/MOVED</filename>.</para>
+ Pick a date that is before the removal but after the
+ last true commit.</para>
</step>
<step>
- <para>If the port had an entry in
- <filename>ports/LEGAL</filename>, restore it.</para>
+ <para>Perform whatever changes are necessary to make
+ the port work again. If it was deleted because the
+ distfiles are no longer available you will need to
+ volunteer to host them yourself, or find someone
+ else to do so.</para>
</step>
<step>
- <para><command>svn commit</command> these changes, preferably in
- one step.</para>
- </step>
+ <para><command>svn add</command> or
+ <command>svn remove</command> any appropriate
+ files.</para>
+ </step>
+
+ <step>
+ <para>Restore the <makevar>SUBDIR</makevar> listing of
+ the port in the parent directory
+ <filename>Makefile</filename>, and delete the entry
+ from <filename>ports/MOVED</filename>.</para>
+ </step>
+
+ <step>
+ <para>If the port had an entry in
+ <filename>ports/LEGAL</filename>, restore it.</para>
+ </step>
+
+ <step>
+ <para><command>svn commit</command> these changes,
+ preferably in one step.</para>
+ </step>
</procedure>
<tip>
- <para><command>addport</command> now detects when the port to
- add has previously existed, and should handle all except
- the <filename>ports/LEGAL</filename> step automatically.</para>
+ <para><command>addport</command> now detects when the
+ port to add has previously existed, and should handle
+ all except the <filename>ports/LEGAL</filename> step
+ automatically.</para>
</tip>
</answer>
</qandaentry>
@@ -3573,39 +3653,42 @@ ControlPersist yes</screen>
<procedure>
<step>
<para>First make sure that you were using an up to
- date ports tree and the target directory does not
- exist.</para>
+ date ports tree and the target directory does
+ not exist.</para>
</step>
<step>
- <para>Use <command>svn move</command> or <command>svn
- copy</command> to do the repo copy.</para>
+ <para>Use <command>svn move</command> or
+ <command>svn copy</command> to do the repo
+ copy.</para>
</step>
<step>
<para>Upgrade the copied port to the new version.
- Remember to change the <makevar>LATEST_LINK</makevar>
- so there are no duplicate ports with the same name.
- In some rare cases it may be necessary to change the
+ Remember to change the
+ <makevar>LATEST_LINK</makevar> so there are no
+ duplicate ports with the same name. In some
+ rare cases it may be necessary to change the
<makevar>PORTNAME</makevar> instead of
- <makevar>LATEST_LINK</makevar>, but this should only
- be done when it is really needed — e.g., using
- an existing port as the base for a very similar
- program with a different name, or upgrading a port to
- a new upstream version which actually changes the
- distribution name, like the transition from
+ <makevar>LATEST_LINK</makevar>, but this should
+ only be done when it is really needed —
+ e.g., using an existing port as the base for a
+ very similar program with a different name, or
+ upgrading a port to a new upstream version which
+ actually changes the distribution name, like the
+ transition from
<filename>textproc/libxml</filename> to
- <filename>textproc/libxml2</filename>. In most cases,
- changing <makevar>LATEST_LINK</makevar> should
- suffice.</para>
+ <filename>textproc/libxml2</filename>. In most
+ cases, changing <makevar>LATEST_LINK</makevar>
+ should suffice.</para>
</step>
<step>
<para>Add the new subdirectory to the
<makevar>SUBDIR</makevar> listing in the parent
- directory <filename>Makefile</filename>. You can run
- <command>make checksubdirs</command> in the parent
- directory to check this.</para>
+ directory <filename>Makefile</filename>. You
+ can run <command>make checksubdirs</command> in
+ the parent directory to check this.</para>
</step>
<step>
@@ -3616,13 +3699,14 @@ ControlPersist yes</screen>
<step>
<para>Add an entry to
- <filename>ports/MOVED</filename>, if you remove the
- original port.</para>
+ <filename>ports/MOVED</filename>, if you remove
+ the original port.</para>
</step>
<step>
- <para>Commit all changes on one commit. A forced commit
- is no longer needed with Subversion.</para>
+ <para>Commit all changes on one commit. A forced
+ commit is no longer needed with
+ Subversion.</para>
</step>
</procedure>
</listitem>
@@ -3632,12 +3716,14 @@ ControlPersist yes</screen>
<procedure>
<step>
- <para>Perform a thorough check of the ports collection for
- any dependencies on the old port location/name, and
- update them. Running <command>grep</command> on
- <filename>INDEX</filename> is not enough because some
- ports have dependencies enabled by compile-time options.
- A full <command>grep -r</command> of the ports
+ <para>Perform a thorough check of the ports
+ collection for any dependencies on the old port
+ location/name, and update them. Running
+ <command>grep</command> on
+ <filename>INDEX</filename> is not enough because
+ some ports have dependencies enabled by
+ compile-time options. A full
+ <command>grep -r</command> of the ports
collection is recommended.</para>
</step>
@@ -3654,14 +3740,16 @@ ControlPersist yes</screen>
</listitem>
<listitem>
- <para>After repo moves (<quote>rename</quote> operations where
- a port is copied and the old location is removed):</para>
+ <para>After repo moves (<quote>rename</quote>
+ operations where a port is copied and the old
+ location is removed):</para>
<procedure>
<step>
- <para>Follow the same steps that are outlined in the
- previous two entries, to activate the new location of
- the port and remove the old one.</para>
+ <para>Follow the same steps that are outlined in
+ the previous two entries, to activate the new
+ location of the port and remove the old
+ one.</para>
</step>
</procedure>
</listitem>
@@ -3683,8 +3771,8 @@ ControlPersist yes</screen>
commits to the ports tree for a short period of time
while the packages and the release itself are being
built. This is to ensure consistency among the various
- parts of the release, and is called the <quote>ports
- freeze</quote>.</para>
+ parts of the release, and is called the
+ <quote>ports freeze</quote>.</para>
<para>For more information on the background and
policies surrounding a ports freeze, see the
@@ -3709,8 +3797,8 @@ ControlPersist yes</screen>
specifically permitted by portmgr. Complete details
about what qualifies as a sweeping change can be found
on the <ulink
- url="&url.base;/portmgr/implementation.html">Portmgr
- Implementation page</ulink>.</para>
+ url="&url.base;/portmgr/implementation.html">Portmgr
+ Implementation page</ulink>.</para>
<para>The benefit of a slush as opposed to a complete
freeze is that it allows maintainers to continue adding
@@ -3745,14 +3833,12 @@ ControlPersist yes</screen>
from the Ports Management Team. <quote>Explicit
approval</quote> here means that you send a patch to
the Ports Management Team for review and get a reply
- saying, <quote>Go ahead and commit it.</quote>
- </para>
+ saying, <quote>Go ahead and commit it.</quote></para>
<para>Not everything is allowed to be committed during
a freeze. Please see the <ulink
url="&url.base;/portmgr/qa.html">Portmgr Quality
- Assurance page</ulink> for more information.
- </para>
+ Assurance page</ulink> for more information.</para>
<para>Note that you do not have implicit permission to fix
a port during the freeze just because it is
@@ -3783,7 +3869,8 @@ ControlPersist yes</screen>
rolled.</para>
<para>When the slush starts, there will be another
- announcement to the &a.ports; and &a.committers;, of course.</para>
+ announcement to the &a.ports; and &a.committers;, of
+ course.</para>
</answer>
</qandaentry>
@@ -3794,12 +3881,12 @@ ControlPersist yes</screen>
<answer>
<para>A few hours after the release, the Ports Management
- Team will send out a mail to the &a.ports; and &a.committers;
- announcing the end of the ports freeze or slush. Note
- that the release being cut does not automatically indicate
- the end of the freeze. We have to make sure there will
- be no last minute snafus that result in an immediate
- re-rolling of the release.</para>
+ Team will send out a mail to the &a.ports; and
+ &a.committers; announcing the end of the ports freeze or
+ slush. Note that the release being cut does not
+ automatically indicate the end of the freeze. We have
+ to make sure there will be no last minute snafus that
+ result in an immediate re-rolling of the release.</para>
</answer>
</qandaentry>
</qandadiv>
@@ -3809,17 +3896,18 @@ ControlPersist yes</screen>
<qandaentry>
<question>
- <para>What is the procedure for creating a new category?</para>
+ <para>What is the procedure for creating a new
+ category?</para>
</question>
<answer>
- <para>Please see
- <ulink url="&url.books.porters-handbook;/makefile-categories.html#PROPOSING-CATEGORIES">
- Proposing a New Category</ulink> in the Porter's Handbook.
- Once that procedure has been followed and the PR has been
- assigned to &a.portmgr;, it is their decision whether or
- not to approve it. If they do, it is their responsibility
- to do the following:</para>
+ <para>Please see <ulink
+ url="&url.books.porters-handbook;/makefile-categories.html#PROPOSING-CATEGORIES">
+ Proposing a New Category</ulink> in the Porter's
+ Handbook. Once that procedure has been followed and the
+ PR has been assigned to &a.portmgr;, it is their
+ decision whether or not to approve it. If they do, it
+ is their responsibility to do the following:</para>
<procedure>
<step>
@@ -3829,8 +3917,8 @@ ControlPersist yes</screen>
<step>
<para>Update the <makevar>VALID_CATEGORIES</makevar>
- definition in <filename>ports/Mk/bsd.port.mk</filename>.
- </para>
+ definition in
+ <filename>ports/Mk/bsd.port.mk</filename>.</para>
</step>
<step>
@@ -3847,132 +3935,139 @@ ControlPersist yes</screen>
</question>
<answer>
- <procedure>
- <step>
- <para>Upgrade each moved port's
- <filename>Makefile</filename>. Do not connect the
- new category to the build yet.</para>
+ <procedure>
+ <step>
+ <para>Upgrade each moved port's
+ <filename>Makefile</filename>. Do not connect the
+ new category to the build yet.</para>
- <para>To do this, you will need to:</para>
- <procedure>
- <step>
- <para>Change the port's <makevar>CATEGORIES</makevar>
- (this was the point of the exercise, remember?)
- The new category should be listed
- <emphasis>first</emphasis>. This will help to
- ensure that the <makevar>PKGORIGIN</makevar>
- is correct.</para>
- </step>
+ <para>To do this, you will need to:</para>
- <step>
- <para>Run a <command>make describe</command>. Since
- the top-level <command>make index</command> that
- you will be running in a few steps is an iteration
- of <command>make describe</command> over the entire
- ports hierarchy, catching any errors here will
- save you having to re-run that step later on.</para>
- </step>
+ <procedure>
+ <step>
+ <para>Change the port's
+ <makevar>CATEGORIES</makevar> (this was the
+ point of the exercise, remember?) The new
+ category should be listed
+ <emphasis>first</emphasis>. This will help to
+ ensure that the <makevar>PKGORIGIN</makevar> is
+ correct.</para>
+ </step>
- <step>
- <para>If you want to be really thorough, now might
- be a good time to run &man.portlint.1;.</para>
- </step>
- </procedure>
- </step>
+ <step>
+ <para>Run a <command>make describe</command>.
+ Since the top-level
+ <command>make index</command> that you will be
+ running in a few steps is an iteration of
+ <command>make describe</command> over the entire
+ ports hierarchy, catching any errors here will
+ save you having to re-run that step later
+ on.</para>
+ </step>
- <step>
- <para>Check that the <makevar>PKGORIGIN</makevar>s are
- correct. The ports system uses each port's
- <makevar>CATEGORIES</makevar> entry to create
- its <makevar>PKGORIGIN</makevar>, which is used to
- connect installed packages to the port directory they
- were built from. If this entry is wrong, common port
- tools like &man.pkg.version.1; and
- &man.portupgrade.1; fail.</para>
+ <step>
+ <para>If you want to be really thorough, now
+ might be a good time to run
+ &man.portlint.1;.</para>
+ </step>
+ </procedure>
+ </step>
- <para>To do this, use the <filename>chkorigin.sh</filename>
- tool, as follows: <command>env
- PORTSDIR=<replaceable>/path/to/ports</replaceable>
- sh -e <replaceable>/path/to/ports</replaceable>/Tools/scripts/chkorigin.sh
- </command>. This will check <emphasis>every</emphasis>
- port in the ports tree, even those not connected to the
- build, so you can run it directly after the move
- operation.
- Hint: do not forget to look at the
- <makevar>PKGORIGIN</makevar>s of any slave ports of the
- ports you just moved!</para>
- </step>
+ <step>
+ <para>Check that the <makevar>PKGORIGIN</makevar>s are
+ correct. The ports system uses each port's
+ <makevar>CATEGORIES</makevar> entry to create its
+ <makevar>PKGORIGIN</makevar>, which is used to
+ connect installed packages to the port directory
+ they were built from. If this entry is wrong,
+ common port tools like &man.pkg.version.1; and
+ &man.portupgrade.1; fail.</para>
- <step>
- <para>On your own local system, test the proposed
- changes: first, comment out the
- <makevar>SUBDIR</makevar> entries in the old
- ports' categories' <filename>Makefile</filename>s;
- then enable building the new category in
- <filename>ports/Makefile</filename>.
- Run <command>make checksubdirs</command> in the
- affected category directories to check the
- <makevar>SUBDIR</makevar> entries. Next, in
- the <filename class="directory">ports/</filename>
- directory, run <command>make index</command>. This
- can take over 40 minutes on even modern systems;
- however, it is a necessary step to prevent problems
- for other people.</para>
- </step>
+ <para>To do this, use the
+ <filename>chkorigin.sh</filename> tool, as follows:
+ <command>env
+ PORTSDIR=<replaceable>/path/to/ports</replaceable>
+ sh -e
+ <replaceable>/path/to/ports</replaceable>/Tools/scripts/chkorigin.sh</command>.
+ This will check <emphasis>every</emphasis> port in
+ the ports tree, even those not connected to the
+ build, so you can run it directly after the move
+ operation. Hint: do not forget to look at the
+ <makevar>PKGORIGIN</makevar>s of any slave ports of
+ the ports you just moved!</para>
+ </step>
- <step>
- <para>Once this is done, you can commit the
- updated <filename>ports/Makefile</filename> to
- connect the new category to the build and also
- commit the <filename>Makefile</filename> changes
- for the old category or categories.</para>
- </step>
+ <step>
+ <para>On your own local system, test the proposed
+ changes: first, comment out the
+ <makevar>SUBDIR</makevar> entries in the old ports'
+ categories' <filename>Makefile</filename>s; then
+ enable building the new category in
+ <filename>ports/Makefile</filename>. Run
+ <command>make checksubdirs</command> in the affected
+ category directories to check the
+ <makevar>SUBDIR</makevar> entries. Next, in the
+ <filename class="directory">ports/</filename>
+ directory, run <command>make index</command>. This
+ can take over 40 minutes on even modern systems;
+ however, it is a necessary step to prevent problems
+ for other people.</para>
+ </step>
- <step>
- <para>Add appropriate entries to
- <filename>ports/MOVED</filename>.</para>
- </step>
+ <step>
+ <para>Once this is done, you can commit the updated
+ <filename>ports/Makefile</filename> to connect the
+ new category to the build and also commit the
+ <filename>Makefile</filename> changes for the old
+ category or categories.</para>
+ </step>
- <step>
- <para>Update the documentation by modifying the
- following:</para>
+ <step>
+ <para>Add appropriate entries to
+ <filename>ports/MOVED</filename>.</para>
+ </step>
- <itemizedlist>
- <listitem>
- <para>the
- <ulink url="&url.books.porters-handbook;/makefile-categories.html#PORTING-CATEGORIES">
- list of categories</ulink> in the Porter's Handbook</para>
- </listitem>
+ <step>
+ <para>Update the documentation by modifying the
+ following:</para>
- <listitem>
- <para>
- <filename>www/en/ports/categories</filename>.
- Note that these are now displayed by sub-groups,
- as specified in
- <filename>www/en/ports/categories.descriptions</filename>.
- </para>
- </listitem>
- </itemizedlist>
- <para>(Note: these are
- in the docs, not the ports, repository). If you
- are not a docs committer, you will need to submit
- a PR for this.</para>
- </step>
+ <itemizedlist>
+ <listitem>
+ <para>the <ulink
+ url="&url.books.porters-handbook;/makefile-categories.html#PORTING-CATEGORIES">list
+ of categories</ulink> in the Porter's
+ Handbook</para>
+ </listitem>
- <step>
- <para>Only once all the above have been done, and
- no one is any longer reporting problems with the
- new ports, should the old ports be deleted from
- their previous locations in the repository.</para>
- </step>
- </procedure>
+ <listitem>
+ <para>
+ <filename>www/en/ports/categories</filename>.
+ Note that these are now displayed by sub-groups,
+ as specified in
+ <filename>www/en/ports/categories.descriptions</filename>.</para>
+ </listitem>
+ </itemizedlist>
- <para>It is not necessary to manually update the <ulink
- url="&url.base;/ports/index.html">ports web pages</ulink>
- to reflect the new category. This is now done automatically
- via your change to <filename>www/en/ports/categories</filename>
- and the daily automated rebuild of <filename>INDEX</filename>.
- </para>
+ <para>(Note: these are in the docs, not the ports,
+ repository). If you are not a docs committer, you
+ will need to submit a PR for this.</para>
+ </step>
+
+ <step>
+ <para>Only once all the above have been done, and no
+ one is any longer reporting problems with the new
+ ports, should the old ports be deleted from their
+ previous locations in the repository.</para>
+ </step>
+ </procedure>
+
+ <para>It is not necessary to manually update the
+ <ulink url="&url.base;/ports/index.html">ports web
+ pages</ulink> to reflect the new category. This is
+ now done automatically via your change to
+ <filename>www/en/ports/categories</filename> and the
+ daily automated rebuild of
+ <filename>INDEX</filename>.</para>
</answer>
</qandaentry>
@@ -3988,9 +4083,10 @@ ControlPersist yes</screen>
<itemizedlist>
<listitem>
- <para>the
- <ulink url="&url.books.porters-handbook;/makefile-categories.html#PORTING-CATEGORIES">
- list of categories</ulink> in the Porter's Handbook</para>
+ <para>the <ulink
+ url="&url.books.porters-handbook;/makefile-categories.html#PORTING-CATEGORIES">list
+ of categories</ulink> in the Porter's
+ Handbook</para>
</listitem>
<listitem>
@@ -4011,21 +4107,22 @@ ControlPersist yes</screen>
</question>
<answer>
- <para>First, go check
- <ulink url="http://pointyhat.FreeBSD.org/errorlogs/"></ulink>.
+ <para>First, go check <ulink
+ url="http://pointyhat.FreeBSD.org/errorlogs/"></ulink>.
There you will find error logs from the latest package
building runs on all supported platforms for the most
recent branches.</para>
- <para>However, just because the port does not show up there
- does not mean it is building correctly. (One of the
- dependencies may have failed, for instance.) The relevant
- directories are available on <hostid>pointyhat</hostid> under
- <filename class="directory">/a/portbuild/<arch>/<major_version></filename>
- so feel free to dig around. Each architecture and version has
- the following subdirectories:</para>
+ <para>However, just because the port does not show up
+ there does not mean it is building correctly. (One of
+ the dependencies may have failed, for instance.) The
+ relevant directories are available on
+ <hostid>pointyhat</hostid> under <filename
+ class="directory">/a/portbuild/<arch>/<major_version></filename>
+ so feel free to dig around. Each architecture and
+ version has the following subdirectories:</para>
-<programlisting>errors error logs from latest <major_version> run on <arch>
+ <programlisting>errors error logs from latest <major_version> run on <arch>
logs all logs from latest <major_version> run on <arch>
packages packages from latest <major_version> run on <arch>
bak/errors error logs from last complete <major_version> run on <arch>
@@ -4050,9 +4147,9 @@ bak/packages packages from last complete <major_version> run on <arch&
<answer>
<para>No, <filename>INDEX</filename> is no longer stored
in the SVN repository. The file can either be generated
- by running <command>make index</command>, or a pre-generated
- version can be downloaded with <command>make
- fetchindex</command>.</para>
+ by running <command>make index</command>, or a
+ pre-generated version can be downloaded with
+ <command>make fetchindex</command>.</para>
</answer>
</qandaentry>
@@ -4063,35 +4160,36 @@ bak/packages packages from last complete <major_version> run on <arch&
</question>
<answer>
- <para>Any file directly under <filename>ports/</filename>, or
- any file under a subdirectory that starts with an
+ <para>Any file directly under <filename>ports/</filename>,
+ or any file under a subdirectory that starts with an
uppercase letter (<filename>Mk/</filename>,
<filename>Tools/</filename>, etc.). In particular, the
Ports Management Team is very protective of
<filename>ports/Mk/bsd.port*.mk</filename> so do not
- commit changes to those files unless you want to face his
- wra(i)th.</para>
+ commit changes to those files unless you want to face
+ his wra(i)th.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
- <para>What is the proper procedure for updating the checksum
- for a port's distfile when the file changes without a
- version change?</para>
+ <para>What is the proper procedure for updating the
+ checksum for a port's distfile when the file changes
+ without a version change?</para>
</question>
<answer>
- <para>When the checksum for a port's distfile is updated due
- to the author updating the file without changing the port's
- revision, the commit message should include a summary of
- the relevant diffs between the original and new distfile to
- ensure that the distfile has not been corrupted or
- maliciously altered. If the current version of the port
- has been in the ports tree for a while, a copy of the old
- distfile will usually be available on the ftp servers;
- otherwise the author or maintainer should be contacted to
- find out why the distfile has changed.</para>
+ <para>When the checksum for a port's distfile is updated
+ due to the author updating the file without changing the
+ port's revision, the commit message should include a
+ summary of the relevant diffs between the original and
+ new distfile to ensure that the distfile has not been
+ corrupted or maliciously altered. If the current
+ version of the port has been in the ports tree for a
+ while, a copy of the old distfile will usually be
+ available on the ftp servers; otherwise the author or
+ maintainer should be contacted to find out why the
+ distfile has changed.</para>
</answer>
</qandaentry>
</qandadiv>
@@ -4099,29 +4197,28 @@ bak/packages packages from last complete <major_version> run on <arch&
</sect1>
<sect1 id="non-committers">
- <title>Issues Specific to Developers Who Are Not Committers</title>
+ <title>Issues Specific to Developers Who Are Not
+ Committers</title>
<para>A few people who have access to the FreeBSD machines do not
have commit bits. For instance, the project is willing to give
- access to the GNATS database to contributors who have shown interest
- and dedication in working on Problem Reports.</para>
+ access to the GNATS database to contributors who have shown
+ interest and dedication in working on Problem Reports.</para>
- <para>Almost all of this document will apply to these developers as
- well (except things specific to commits and the mailing list
- memberships that go with them). In particular, we recommend that
- you read:</para>
+ <para>Almost all of this document will apply to these developers
+ as well (except things specific to commits and the mailing list
+ memberships that go with them). In particular, we recommend
+ that you read:</para>
<itemizedlist>
<listitem>
- <para>
- <link linkend="admin">Administrative Details</link>
- </para>
+ <para><link linkend="admin">Administrative
+ Details</link></para>
</listitem>
<listitem>
- <para>
- <link linkend="conventions-everyone">Conventions</link>
- </para>
+ <para><link
+ linkend="conventions-everyone">Conventions</link></para>
<note>
<para>You should get your mentor to add you to the
@@ -4132,21 +4229,19 @@ bak/packages packages from last complete <major_version> run on <arch&
</listitem>
<listitem>
- <para>
- <link linkend="developer.relations">Developer Relations</link>
- </para>
+ <para><link
+ linkend="developer.relations">Developer
+ Relations</link></para>
</listitem>
<listitem>
- <para>
- <link linkend="ssh.guide">SSH Quick-Start Guide</link>
- </para>
+ <para><link linkend="ssh.guide">SSH Quick-Start
+ Guide</link></para>
</listitem>
<listitem>
- <para>
- <link linkend="rules">The FreeBSD Committers' Big List of Rules</link>
- </para>
+ <para><link linkend="rules">The FreeBSD Committers' Big List
+ of Rules</link></para>
</listitem>
</itemizedlist>
@@ -4165,12 +4260,12 @@ bak/packages packages from last complete <major_version> run on <arch&
<title>&ga; General Policy</title>
<para>The &os; Project takes visitor privacy very
- seriously. As such, the &os; Project website honors the
- <quote>Do Not Track</quote> header <emphasis>before</emphasis>
- fetching the tracking code from Google. For more information,
- please see the <ulink
- url="http://www.FreeBSD.org/privacy.html">&os; Privacy
- Policy</ulink>.</para>
+ seriously. As such, the &os; Project website honors the
+ <quote>Do Not Track</quote> header <emphasis>before</emphasis>
+ fetching the tracking code from Google. For more information,
+ please see the
+ <ulink url="http://www.FreeBSD.org/privacy.html">&os; Privacy
+ Policy</ulink>.</para>
<para>&ga; access is <emphasis>not</emphasis> arbitrarily
allowed — access must be requested, voted on by the
@@ -4222,10 +4317,10 @@ bak/packages packages from last complete <major_version> run on <arch&
<sect1 id="perks">
<title>Perks of the Job</title>
- <para>Unfortunately, there are not many perks involved with being a
- committer. Recognition as a competent software engineer is probably
- the only thing that will be of benefit in the long run. However,
- there are at least some perks:</para>
+ <para>Unfortunately, there are not many perks involved with being
+ a committer. Recognition as a competent software engineer is
+ probably the only thing that will be of benefit in the long run.
+ However, there are at least some perks:</para>
<variablelist>
<varlistentry>
@@ -4234,22 +4329,24 @@ bak/packages packages from last complete <major_version> run on <arch&
<listitem>
<para>&os; committers can get a free 4-CD or DVD set at
conferences from <ulink url="http://www.freebsdmall.com">
- &os; Mall, Inc.</ulink>. The sets are no longer available
- as a subscription due to the high shipment costs to
- countries outside the USA.</para>
+ &os; Mall, Inc.</ulink>. The sets are no longer
+ available as a subscription due to the high shipment costs
+ to countries outside the USA.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>Freenode IRC Cloaks</term>
+ <term>Freenode IRC Cloaks</term>
<listitem>
- <para>&os; developers may request a cloaked hostmask for their
- account on the Freenode IRC network in the form of
- <literal>freebsd/developer/</literal><replaceable>freefall name</replaceable>
- or <literal>freebsd/developer/</literal><replaceable>NickServ name</replaceable>.
- To request a cloak, send an email to &a.eadler; with your
- requested hostmask and NickServ account name.</para>
+ <para>&os; developers may request a cloaked hostmask for
+ their account on the Freenode IRC network in the form of
+ <literal>freebsd/developer/</literal><replaceable>freefall
+ name</replaceable> or
+ <literal>freebsd/developer/</literal><replaceable>NickServ
+ name</replaceable>. To request a cloak, send an email to
+ &a.eadler; with your requested hostmask and NickServ
+ account name.</para>
</listitem>
</varlistentry>
</variablelist>
@@ -4261,20 +4358,21 @@ bak/packages packages from last complete <major_version> run on <arch&
<qandaset>
<qandaentry>
<question>
- <para>Why are trivial or cosmetic changes to files on a vendor
- branch a bad idea?</para>
+ <para>Why are trivial or cosmetic changes to files on a
+ vendor branch a bad idea?</para>
</question>
<answer>
<itemizedlist>
<listitem>
- <para>From now on, every new vendor release of that file will
- need to have patches merged in by hand.</para>
+ <para>From now on, every new vendor release of that file
+ will need to have patches merged in by hand.</para>
</listitem>
<listitem>
- <para>From now on, every new vendor release of that file will
- need to have patches <emphasis>verified</emphasis> by hand.</para>
+ <para>From now on, every new vendor release of that file
+ will need to have patches
+ <emphasis>verified</emphasis> by hand.</para>
</listitem>
</itemizedlist>
</answer>
@@ -4287,34 +4385,34 @@ bak/packages packages from last complete <major_version> run on <arch&
<answer>
<para>To add a file onto a branch, simply checkout or update
- to the branch you want to add to and then add the file using
- the add operation as you normally would. This works
- fine for the <literal>doc</literal> and
- <literal>ports</literal> trees. The <literal>src</literal>
- tree uses SVN and requires more care because of the
- <literal>mergeinfo</literal> properties. See section 1.4.6
- of the <ulink url="http://wiki.freebsd.org/SubversionPrimer">
- Subversion Primer</ulink> for details. Refer to <ulink
- url="http://wiki.freebsd.org/SubversionPrimer/Merging">
- SubversionPrimer/Merging</ulink> for details on how to
- perform an MFC.</para>
+ to the branch you want to add to and then add the file
+ using the add operation as you normally would. This works
+ fine for the <literal>doc</literal> and
+ <literal>ports</literal> trees. The
+ <literal>src</literal> tree uses SVN and requires more
+ care because of the <literal>mergeinfo</literal>
+ properties. See section 1.4.6 of the <ulink
+ url="http://wiki.freebsd.org/SubversionPrimer">Subversion
+ Primer</ulink> for details. Refer to <ulink
+ url="http://wiki.freebsd.org/SubversionPrimer/Merging">SubversionPrimer/Merging</ulink>
+ for details on how to perform an MFC.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
- <para>What <quote>meta</quote> information should I include in a
- commit message?</para>
+ <para>What <quote>meta</quote> information should I include
+ in a commit message?</para>
</question>
<answer>
- <para>As well as including an informative message with each commit
- you may need to include some additional information as
- well.</para>
+ <para>As well as including an informative message with each
+ commit you may need to include some additional information
+ as well.</para>
- <para>This information consists of one or more lines containing the
- key word or phrase, a colon, tabs for formatting, and then the
- additional information.</para>
+ <para>This information consists of one or more lines
+ containing the key word or phrase, a colon, tabs for
+ formatting, and then the additional information.</para>
<para>The key words or phrases are:</para>
@@ -4324,60 +4422,60 @@ bak/packages packages from last complete <major_version> run on <arch&
<row>
<entry><literal>PR:</literal></entry>
<entry>The problem report (if any) which is affected
- (typically, by being closed) by this commit.</entry>
+ (typically, by being closed) by this
+ commit.</entry>
</row>
<row>
<entry><literal>Submitted by:</literal></entry>
- <entry>The name and e-mail address of the person that
- submitted the fix; for committers, just the username on
- the FreeBSD cluster.</entry>
+ <entry>The name and e-mail address of the person
+ that submitted the fix; for committers, just the
+ username on the FreeBSD cluster.</entry>
</row>
<row>
<entry><literal>Reviewed by:</literal></entry>
- <entry>The name and e-mail address of the person or people
- that reviewed the change; for committers, just the
- username on the FreeBSD cluster. If a patch was
- submitted to a mailing list for review, and the review
- was favorable, then just include the list name.</entry>
+ <entry>The name and e-mail address of the person or
+ people that reviewed the change; for committers,
+ just the username on the FreeBSD cluster. If a
+ patch was submitted to a mailing list for review,
+ and the review was favorable, then just include
+ the list name.</entry>
</row>
<row>
<entry><literal>Approved by:</literal></entry>
- <entry>The name and e-mail address of the person or people
- that approved the change; for committers, just the
- username on the FreeBSD cluster. It is customary to get
- prior approval for a commit if it is to an area of the
- tree to which you do not usually commit. In addition,
- during the run up to a new release all commits
- <emphasis>must</emphasis> be approved by the release
- engineering team. If these are your first commits then
- you should have passed them past your mentor first, and
- you should list your mentor, as in
- ``<replaceable>username-of-mentor</replaceable>
- <literal>(mentor)</literal>''.
- </entry>
+ <entry>The name and e-mail address of the person or
+ people that approved the change; for committers,
+ just the username on the FreeBSD cluster. It is
+ customary to get prior approval for a commit if it
+ is to an area of the tree to which you do not
+ usually commit. In addition, during the run up to
+ a new release all commits
+ <emphasis>must</emphasis> be approved by the
+ release engineering team. If these are your first
+ commits then you should have passed them past your
+ mentor first, and you should list your mentor, as
+ in ``<replaceable>username-of-mentor</replaceable>
+ <literal>(mentor)</literal>''.</entry>
</row>
<row>
<entry><literal>Obtained from:</literal></entry>
- <entry>The name of the project (if any) from which the code
- was obtained.</entry>
+ <entry>The name of the project (if any) from which
+ the code was obtained.</entry>
</row>
<row>
<entry><literal>MFC after:</literal></entry>
-
<entry>If you wish to receive an e-mail reminder to
- <acronym>MFC</acronym> at a later date, specify the
- number of days, weeks, or months after which an
- <acronym>MFC</acronym> is planned.</entry>
+ <acronym>MFC</acronym> at a later date, specify
+ the number of days, weeks, or months after which
+ an <acronym>MFC</acronym> is planned.</entry>
</row>
<row>
<entry><literal>Security:</literal></entry>
-
<entry>If the change is related to a security
vulnerability or security exposure, include one or
more references or a description of the
@@ -4390,9 +4488,9 @@ bak/packages packages from last complete <major_version> run on <arch&
<example>
<title>Commit Log for a Commit Based on a PR</title>
- <para>You want to commit a change based on a PR submitted by John
- Smith containing a patch. The end of the commit message should
- look something like this.</para>
+ <para>You want to commit a change based on a PR submitted
+ by John Smith containing a patch. The end of the commit
+ message should look something like this.</para>
<programlisting>...
@@ -4403,10 +4501,10 @@ Submitted by: John Smith <John.Smith@example.com></programlisting>
<example>
<title>Commit Log for a Commit Needing Review</title>
- <para>You want to change the virtual memory system. You have
- posted patches to the appropriate mailing list (in this case,
- <literal>freebsd-arch</literal>) and the changes have been
- approved.</para>
+ <para>You want to change the virtual memory system. You
+ have posted patches to the appropriate mailing list (in
+ this case, <literal>freebsd-arch</literal>) and the
+ changes have been approved.</para>
<programlisting>...
@@ -4416,24 +4514,25 @@ Reviewed by: -arch</programlisting>
<example>
<title>Commit Log for a Commit Needing Approval</title>
- <para>You want to commit a change to a section of the tree with a
- MAINTAINER assigned. You have collaborated with the listed
- MAINTAINER, who has told you to go ahead and commit.</para>
+ <para>You want to commit a change to a section of the tree
+ with a MAINTAINER assigned. You have collaborated with
+ the listed MAINTAINER, who has told you to go ahead and
+ commit.</para>
<programlisting>...
Approved by: <replaceable>abc</replaceable></programlisting>
- <para>Where <replaceable>abc</replaceable> is the account name of
- the person who approved.</para>
+ <para>Where <replaceable>abc</replaceable> is the account
+ name of the person who approved.</para>
</example>
<example>
<title>Commit Log for a Commit Bringing in Code from
OpenBSD</title>
- <para>You want to commit some code based on work done in the
- OpenBSD project.</para>
+ <para>You want to commit some code based on work done in
+ the OpenBSD project.</para>
<programlisting>...
@@ -4441,38 +4540,42 @@ Obtained from: OpenBSD</programlisting>
</example>
<example>
- <title>Commit Log for a Change to &os.current; with a Planned
- Commit to &os.stable; to Follow at a Later Date.</title>
+ <title>Commit Log for a Change to &os.current; with a
+ Planned Commit to &os.stable; to Follow at a Later
+ Date.</title>
- <para>You want to commit some code which will be merged from
- &os.current; into the &os.stable; branch after two
+ <para>You want to commit some code which will be merged
+ from &os.current; into the &os.stable; branch after two
weeks.</para>
<programlisting>...
MFC after: <replaceable>2 weeks</replaceable></programlisting>
- <para>Where <replaceable>2</replaceable> is the number of days,
- weeks, or months after which an <acronym>MFC</acronym> is
- planned. The <replaceable>weeks</replaceable> option may be
+ <para>Where <replaceable>2</replaceable> is the number of
+ days, weeks, or months after which an
+ <acronym>MFC</acronym> is planned. The
+ <replaceable>weeks</replaceable> option may be
<literal>day</literal>, <literal>days</literal>,
<literal>week</literal>, <literal>weeks</literal>,
- <literal>month</literal>, <literal>months</literal>,
- or may be left off (in which case, days will be assumed).</para>
+ <literal>month</literal>, <literal>months</literal>, or
+ may be left off (in which case, days will be
+ assumed).</para>
</example>
- <para>In some cases you may need to combine some of these.</para>
+ <para>In some cases you may need to combine some of
+ these.</para>
<para>Consider the situation where a user has submitted a PR
- containing code from the NetBSD project. You are looking at the
- PR, but it is not an area of the tree you normally work in, so
- you have decided to get the change reviewed by the
- <literal>arch</literal> mailing list. Since the change is
- complex, you opt to <acronym>MFC</acronym> after one month to
- allow adequate testing.</para>
+ containing code from the NetBSD project. You are looking
+ at the PR, but it is not an area of the tree you normally
+ work in, so you have decided to get the change reviewed by
+ the <literal>arch</literal> mailing list. Since the
+ change is complex, you opt to <acronym>MFC</acronym> after
+ one month to allow adequate testing.</para>
- <para>The extra information to include in the commit would look
- something like</para>
+ <para>The extra information to include in the commit would
+ look something like</para>
<programlisting>PR: foo/54321
Submitted by: John Smith <John.Smith@example.com>
@@ -4484,18 +4587,19 @@ MFC after: 1 month</programlisting>
<qandaentry>
<question>
- <para>How do I access <hostid
- role="fqdn">people.FreeBSD.org</hostid> to put up personal
- or project information?</para>
+ <para>How do I access
+ <hostid role="fqdn">people.FreeBSD.org</hostid> to put up
+ personal or project information?</para>
</question>
<answer>
<para><hostid role="fqdn">people.FreeBSD.org</hostid> is the
- same as <hostid
- role="fqdn">freefall.FreeBSD.org</hostid>. Just create a
- <filename>public_html</filename> directory. Anything you
- place in that directory will automatically be visible
- under <ulink url="http://people.FreeBSD.org/"></ulink>.</para>
+ same as
+ <hostid role="fqdn">freefall.FreeBSD.org</hostid>. Just
+ create a <filename>public_html</filename> directory.
+ Anything you place in that directory will automatically be
+ visible under <ulink
+ url="http://people.FreeBSD.org/"></ulink>.</para>
</answer>
</qandaentry>
@@ -4505,9 +4609,11 @@ MFC after: 1 month</programlisting>
</question>
<answer>
- <para>The mailing lists are archived under <filename>/g/mail</filename>
- which will show up as <filename>/hub/g/mail</filename> with &man.pwd.1;.
- This location is accessible from any machine on the FreeBSD cluster.</para>
+ <para>The mailing lists are archived under
+ <filename>/g/mail</filename> which will show up as
+ <filename>/hub/g/mail</filename> with &man.pwd.1;. This
+ location is accessible from any machine on the FreeBSD
+ cluster.</para>
</answer>
</qandaentry>
@@ -4519,9 +4625,9 @@ MFC after: 1 month</programlisting>
<answer>
<para>See the <ulink
- url="http://www.freebsd.org/internal/new-account.html">New
- Account Creation Procedure</ulink> document on the internal
- pages.</para>
+ url="http://www.freebsd.org/internal/new-account.html">New
+ Account Creation Procedure</ulink> document on the
+ internal pages.</para>
</answer>
</qandaentry>
</qandaset>