svn commit: r43437 - head/en_US.ISO8859-1/articles/committers-guide
Warren Block
wblock at FreeBSD.org
Sun Jan 5 22:45:51 UTC 2014
Author: wblock
Date: Sun Jan 5 22:45:51 2014
New Revision: 43437
URL: http://svnweb.freebsd.org/changeset/doc/43437
Log:
Whitespace-only fixes, translators please ignore.
Modified:
head/en_US.ISO8859-1/articles/committers-guide/article.xml
Modified: head/en_US.ISO8859-1/articles/committers-guide/article.xml
==============================================================================
--- head/en_US.ISO8859-1/articles/committers-guide/article.xml Sun Jan 5 21:59:57 2014 (r43436)
+++ head/en_US.ISO8859-1/articles/committers-guide/article.xml Sun Jan 5 22:45:51 2014 (r43437)
@@ -3,11 +3,17 @@
"http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd" [
<!ENTITY ga "Google Analytics">
]>
-<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
- <info><title>Committer's Guide</title>
-
- <author><orgname>The &os; Documentation Project</orgname></author>
+<article xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+ xml:lang="en">
+
+ <info>
+ <title>Committer's Guide</title>
+
+ <author>
+ <orgname>The &os; Documentation Project</orgname>
+ </author>
<copyright>
<year>1999</year>
@@ -52,7 +58,8 @@
more repositories. However, a few developers do not, and some
of the information here applies to them as well. (For
instance, some people only have rights to work with the
- Problem Report database). Please see <xref linkend="non-committers"/> for more information.</para>
+ Problem Report database). Please see
+ <xref linkend="non-committers"/> for more information.</para>
<para>This document may also be of interest to members of the
&os; community who want to learn more about how the project
@@ -75,28 +82,36 @@
<row>
<entry><emphasis>Main Shell Host</emphasis></entry>
- <entry><systemitem class="fqdomainname">freefall.FreeBSD.org</systemitem></entry>
+ <entry><systemitem
+ class="fqdomainname">freefall.FreeBSD.org</systemitem></entry>
</row>
<row>
<entry><emphasis><literal>src/</literal> Subversion
Root</emphasis></entry>
- <entry><literal>svn+ssh://</literal><systemitem class="fqdomainname">svn.FreeBSD.org</systemitem><filename>/base</filename>
- (see also <xref linkend="svn-getting-started-base-layout"/>).</entry>
+ <entry><literal>svn+ssh://</literal><systemitem
+ class="fqdomainname">svn.FreeBSD.org</systemitem><filename>/base</filename>
+ (see also <xref
+ linkend="svn-getting-started-base-layout"/>).</entry>
</row>
<row>
<entry><emphasis><literal>doc/</literal> Subversion
Root</emphasis></entry>
- <entry><literal>svn+ssh://</literal><systemitem class="fqdomainname">svn.FreeBSD.org</systemitem><filename>/doc</filename>
- (see also <xref linkend="svn-getting-started-doc-layout"/>).</entry>
+ <entry><literal>svn+ssh://</literal><systemitem
+ class="fqdomainname">svn.FreeBSD.org</systemitem><filename>/doc</filename>
+ (see also <xref
+ linkend="svn-getting-started-doc-layout"/>).</entry>
</row>
<row>
<entry><emphasis><literal>ports/</literal> Subversion
Root</emphasis></entry>
- <entry><literal>svn+ssh://</literal><systemitem class="fqdomainname">svn.FreeBSD.org</systemitem><filename>/ports</filename>
- (see also <xref linkend="svn-getting-started-ports-layout"/>).</entry>
+
+ <entry><literal>svn+ssh://</literal><systemitem
+ class="fqdomainname">svn.FreeBSD.org</systemitem><filename>/ports</filename>
+ (see also <xref
+ linkend="svn-getting-started-ports-layout"/>).</entry>
</row>
<row>
@@ -110,7 +125,8 @@
<filename>/home/mail/repository-name-developers-archive</filename>
and
<filename>/home/mail/repository-name-committers-archive</filename>
- on the <systemitem class="fqdomainname">FreeBSD.org</systemitem>
+ on the <systemitem
+ class="fqdomainname">FreeBSD.org</systemitem>
cluster.)</entry>
</row>
@@ -119,7 +135,8 @@
<entry><emphasis>Core Team monthly
reports</emphasis></entry>
<entry><filename>/home/core/public/monthly-reports</filename>
- on the <systemitem class="fqdomainname">FreeBSD.org</systemitem>
+ on the <systemitem
+ class="fqdomainname">FreeBSD.org</systemitem>
cluster.</entry>
</row>
@@ -127,7 +144,8 @@
<entry><emphasis>Ports Management Team monthly
reports</emphasis></entry>
<entry><filename>/home/portmgr/public/monthly-reports</filename>
- on the <systemitem class="fqdomainname">FreeBSD.org</systemitem>
+ on the <systemitem
+ class="fqdomainname">FreeBSD.org</systemitem>
cluster.</entry>
</row>
@@ -156,13 +174,14 @@
</listitem>
<listitem>
- <para><link xlink:href="&url.base;/internal/machines.html">&os; Project
- Hosts</link></para>
+ <para><link
+ xlink:href="&url.base;/internal/machines.html">&os;
+ Project Hosts</link></para>
</listitem>
<listitem>
- <para><link xlink:href="&url.base;/administration.html">&os; Project
- Administrative Groups</link></para>
+ <para><link xlink:href="&url.base;/administration.html">&os;
+ Project Administrative Groups</link></para>
</listitem>
</itemizedlist>
</sect1>
@@ -171,12 +190,12 @@
<title>Open<acronym>PGP</acronym> Keys for &os;</title>
<para>Cryptographic keys conforming to the
- Open<acronym>PGP</acronym>
- (<emphasis>Pretty Good Privacy</emphasis>) standard are used by
- the &os; project to authenticate committers. Messages carrying
- important information like public <acronym>SSH</acronym> keys
- can be signed with the Open<acronym>PGP</acronym> key to prove
- that they are really from the committer. See
+ Open<acronym>PGP</acronym> (<emphasis>Pretty Good
+ Privacy</emphasis>) standard are used by the &os; project to
+ authenticate committers. Messages carrying important
+ information like public <acronym>SSH</acronym> keys can be
+ signed with the Open<acronym>PGP</acronym> key to prove that
+ they are really from the committer. See
<link xlink:href="http://www.nostarch.com/pgp_ml.htm">PGP &
GPG: Email for the Practical Paranoid by Michael Lucas</link>
and <link
@@ -247,7 +266,8 @@ You need a Passphrase to protect your se
<callout arearefs="co-pgp-bits">
<para>2048-bit keys with a three-year expiration provide
adequate protection at present (2013-12). <link
- xlink:href="http://danielpocock.com/rsa-key-sizes-2048-or-4096-bits"/> describes the situation in more detail.</para>
+ xlink:href="http://danielpocock.com/rsa-key-sizes-2048-or-4096-bits"/>
+ describes the situation in more detail.</para>
</callout>
<callout arearefs="co-pgp-expire">
@@ -288,8 +308,8 @@ You need a Passphrase to protect your se
<sect1 xml:id="committer.types">
<title>Commit Bit Types</title>
- <para>The &os; repository has a number of components which,
- when combined, support the basic operating system source,
+ <para>The &os; repository has a number of components which, when
+ combined, support the basic operating system source,
documentation, third party application ports infrastructure, and
various maintained utilities. When &os; commit bits are
allocated, the areas of the tree where the bit may be used are
@@ -387,11 +407,14 @@ You need a Passphrase to protect your se
<para>It is assumed that you are already familiar with the basic
operation of Subversion. If not, start by reading the
- <link xlink:href="http://svnbook.red-bean.com/">Subversion Book</link>.</para>
+ <link xlink:href="http://svnbook.red-bean.com/">Subversion
+ Book</link>.</para>
- <para><link xlink:href="http://wiki.freebsd.org/SubversionMissing">There
+ <para><link
+ xlink:href="http://wiki.freebsd.org/SubversionMissing">There
is a list of things missing in Subversion when compared to
- CVS</link>. The notes at <uri xlink:href="http://people.freebsd.org/~peter/svn_notes.txt">http://people.freebsd.org/~peter/svn_notes.txt</uri>
+ CVS</link>. The notes at <uri
+ xlink:href="http://people.freebsd.org/~peter/svn_notes.txt">http://people.freebsd.org/~peter/svn_notes.txt</uri>
might also be useful.</para>
<sect2 xml:id="svn-intro">
@@ -525,11 +548,12 @@ You need a Passphrase to protect your se
</note>
<para>The above command will check out a
- <literal>CURRENT</literal> source tree as <filename>/usr/src/</filename>,
- which can be any target directory on the local filesystem.
- Omitting the final argument of that command causes the
- working copy, in this case, to be named <quote>head</quote>,
- but that can be renamed safely.</para>
+ <literal>CURRENT</literal> source tree as
+ <filename>/usr/src/</filename>, which can be any target
+ directory on the local filesystem. Omitting the final
+ argument of that command causes the working copy, in this
+ case, to be named <quote>head</quote>, but that can be
+ renamed safely.</para>
<para><literal>svn+ssh</literal> means the
<acronym>SVN</acronym> protocol tunnelled over
@@ -694,13 +718,13 @@ You need a Passphrase to protect your se
<title>&os; Ports Tree Branches and Layout</title>
<para>In <literal>svn+ssh://svn.freebsd.org/ports</literal>,
- <emphasis>ports</emphasis> refers to the repository root of the
- ports tree.</para>
+ <emphasis>ports</emphasis> refers to the repository root of
+ the ports tree.</para>
- <para>In general, most &os; port work will be done within
- the <filename>head/</filename> branch of the ports tree
- which is the actual ports tree used to install software.
- Some other key locations are:</para>
+ <para>In general, most &os; port work will be done within the
+ <filename>head/</filename> branch of the ports tree which is
+ the actual ports tree used to install software. Some other
+ key locations are:</para>
<itemizedlist>
<listitem>
@@ -815,12 +839,14 @@ You need a Passphrase to protect your se
<para>It is possible to anonymously check out the &os;
repository with Subversion. This will give access to a
read-only tree that can be updated, but not committed back
- to the main repository. To do this, use the following command:</para>
+ to the main repository. To do this, use the following
+ command:</para>
<screen>&prompt.user; <userinput>svn co https://svn0.us-west.FreeBSD.org/base/head /usr/src</userinput></screen>
<para>Select the closest mirror and verify the mirror server
- certificate from the list of <link xlink:href="&url.books.handbook;/svn-mirrors.html">Subversion
+ certificate from the list of <link
+ xlink:href="&url.books.handbook;/svn-mirrors.html">Subversion
mirror sites</link>.</para>
</sect3>
@@ -860,9 +886,10 @@ You need a Passphrase to protect your se
<screen>&prompt.user; <userinput>svn commit</userinput></screen>
- <para>To commit all changes in, for example, <filename>lib/libfetch/</filename>
- and <filename>usr/bin/fetch/</filename>
- in a single operation:</para>
+ <para>To commit all changes in, for example,
+ <filename>lib/libfetch/</filename> and
+ <filename>usr/bin/fetch/</filename> in a single
+ operation:</para>
<screen>&prompt.user; <userinput>svn commit lib/libfetch usr/bin/fetch</userinput></screen>
@@ -878,16 +905,17 @@ You need a Passphrase to protect your se
<title>Adding and Removing Files</title>
<note>
- <para>Before adding files, get a copy of <link xlink:href="http://people.freebsd.org/~peter/auto-props.txt">auto-props.txt</link>
- (there is also a <link xlink:href="http://people.freebsd.org/~beat/cvs2svn/auto-props.txt">
- ports tree specific version</link>)
- and add it to <filename>~/.subversion/config</filename>
- according to the instructions in the file. If you added
- something before reading this, use
- <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
+ <para>Before adding files, get a copy of <link
+ xlink:href="http://people.freebsd.org/~peter/auto-props.txt">auto-props.txt</link>
+ (there is also a <link
+ xlink:href="http://people.freebsd.org/~beat/cvs2svn/auto-props.txt">
+ ports tree specific version</link>) and add it to
+ <filename>~/.subversion/config</filename> according to the
+ instructions in the file. If you added something before
+ reading this, use <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>
</note>
@@ -900,9 +928,9 @@ You need a Passphrase to protect your se
<note>
<para>Most new source files should include a
- <literal>$&os;$</literal> string near the start of the
- file. On commit, <command>svn</command> will expand
- the <literal>$&os;$</literal> string,
+ <literal>$&os;$</literal> string near the
+ start of the file. On commit, <command>svn</command> will
+ expand the <literal>$&os;$</literal> string,
adding the file path, revision number, date and time of
commit, and the username of the committer. Files which
cannot be modified may be committed without the
@@ -1219,22 +1247,23 @@ You need a Passphrase to protect your se
<listitem>
<para>If a direct descendant of
- <filename>branch/foo/bar/</filename>
- (for instance, <filename>branch/foo/bar/baz/</filename>)
- already has a mergeinfo record, information about the
- current merge will be propagated down to it.</para>
+ <filename>branch/foo/bar/</filename> (for instance,
+ <filename>branch/foo/bar/baz/</filename>) already has
+ a mergeinfo record, information about the current
+ merge will be propagated down to it.</para>
</listitem>
</orderedlist>
<para>If you consider the case where a revision changes
- several separate parts of the tree (for example, <filename>branch/foo/bar/</filename> and
- <filename>branch/foo/quux/</filename>),
- but you only want to merge some of it (for example,
- <filename>branch/foo/bar/</filename>),
- you will see that these rules make sense. If mergeinfo
- was propagated up, it would seem like that revision had
- also been merged to <filename>branch/foo/quux/</filename>, when in
- fact it had not been.</para>
+ several separate parts of the tree (for example,
+ <filename>branch/foo/bar/</filename> and
+ <filename>branch/foo/quux/</filename>), but you only want
+ to merge some of it (for example,
+ <filename>branch/foo/bar/</filename>), you will see that
+ these rules make sense. If mergeinfo was propagated up,
+ it would seem like that revision had also been merged to
+ <filename>branch/foo/quux/</filename>, when in fact it had
+ not been.</para>
</sect4>
<sect4 xml:id="merge">
@@ -1288,32 +1317,29 @@ You need a Passphrase to protect your se
<listitem>
<para>Changes to kernel code should be merged to
- <filename>sys/</filename>. For
- instance, a change to the &man.ichwd.4; driver should
- be merged to
-
+ <filename>sys/</filename>. For instance, a change to
+ the &man.ichwd.4; driver should be merged to
+ <filename>sys/</filename>, not
+ <filename>sys/dev/ichwd/</filename>. Likewise, a
+ change to the TCP/IP stack should be merged to
<filename>sys/</filename>, not
- <filename>sys/dev/ichwd/</filename>.
- Likewise, a change to the TCP/IP stack should be
- merged to <filename>sys/</filename>,
- not <filename>sys/netinet/</filename>.</para>
+ <filename>sys/netinet/</filename>.</para>
</listitem>
<listitem>
- <para>Changes to code under
- <filename>etc/</filename> should be
- merged at <filename>etc/</filename>,
- not below it.</para>
+ <para>Changes to code under <filename>etc/</filename>
+ should be merged at <filename>etc/</filename>, not
+ below it.</para>
</listitem>
<listitem>
<para>Changes to vendor code (code in
-
<filename>contrib/</filename>,
- <filename>crypto/</filename> and so
- on) should be merged to the directory where vendor
- imports happen. For instance, a change to <filename>crypto/openssl/util/</filename>
- should be merged to <filename>crypto/openssl/</filename>. This
+ <filename>crypto/</filename> and so on) should be
+ merged to the directory where vendor imports happen.
+ For instance, a change to
+ <filename>crypto/openssl/util/</filename> should be
+ merged to <filename>crypto/openssl/</filename>. This
is rarely an issue, however, since changes to vendor
code are usually merged wholesale.</para>
</listitem>
@@ -1322,41 +1348,39 @@ You need a Passphrase to protect your se
<para>Changes to userland programs should as a general
rule be merged to the directory that contains the
Makefile for that program. For instance, a change to
- <filename>usr.bin/xlint/arch/i386/</filename>
- should be merged to <filename>usr.bin/xlint/</filename>.</para>
+ <filename>usr.bin/xlint/arch/i386/</filename> should
+ be merged to
+ <filename>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
Makefile for that library. For instance, a change to
- <filename>lib/libc/gen/</filename>
- should be merged to <filename>lib/libc/</filename>.</para>
+ <filename>lib/libc/gen/</filename> should be merged to
+ <filename>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.
- For instance, everything under <filename>lib/libpam/</filename> is merged
- to <filename>lib/libpam/</filename>,
- even though the library itself and all of the modules
- each have their own Makefile.</para>
+ For instance, everything under
+ <filename>lib/libpam/</filename> is merged to
+ <filename>lib/libpam/</filename>, 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>share/man/manN/</filename>,
- for the appropriate value of
- <literal>N</literal>.</para>
+ <filename>share/man/manN/</filename>, for the
+ appropriate value of <literal>N</literal>.</para>
</listitem>
<listitem>
- <para>Other changes to
- <filename>share/</filename> should
- be merged to the appropriate subdirectory and not to
- <filename>share/</filename>
- directly.</para>
-
+ <para>Other changes to <filename>share/</filename>
+ should be merged to the appropriate subdirectory and
+ not to <filename>share/</filename> directly.</para>
</listitem>
<listitem>
@@ -1385,14 +1409,14 @@ You need a Passphrase to protect your se
in one go.</para>
<para>The source will almost invariably be the same as the
- target. For instance, you will always merge <filename>stable/7/lib/libc/</filename> from
- <filename>head/lib/libc/</filename>.
- The only exception would be when merging changes to code
- that has moved in the source branch but not in the parent
- branch. For instance, a change to &man.pkill.1; would be
- merged from <filename>bin/pkill/</filename> in head to
- <filename>usr.bin/pkill/</filename> in
- stable/7.</para>
+ target. For instance, you will always merge
+ <filename>stable/7/lib/libc/</filename> from
+ <filename>head/lib/libc/</filename>. The only exception
+ would be when merging changes to code that has moved in
+ the source branch but not in the parent branch. For
+ instance, a change to &man.pkill.1; would be merged from
+ <filename>bin/pkill/</filename> in head to
+ <filename>usr.bin/pkill/</filename> in stable/7.</para>
</sect4>
<sect4>
@@ -1489,12 +1513,13 @@ $target - head/$source:$P,$Q,$R</screen>
<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>head/share/man/man4</filename> and
- according to <xref linkend="svn-advanced-use-merging"/>
- 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="svn-getting-started-base-layout"/>.</para>
+ The file resides in
+ <filename>head/share/man/man4</filename> and according
+ to <xref linkend="svn-advanced-use-merging"/> 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="svn-getting-started-base-layout"/>.</para>
<para>The first step is to inspect the existing
mergeinfo.</para>
@@ -2032,13 +2057,15 @@ U stable/9/share/man/man4/netmap.4
is dead (although you can have a new branch with the same
name after you delete the branch if you want).</para>
- <para>As per <link xlink:href="http://people.freebsd.org/~peter/svn_notes.txt">http://people.freebsd.org/~peter/svn_notes.txt</link>,
+ <para>As per <link
+ xlink:href="http://people.freebsd.org/~peter/svn_notes.txt">http://people.freebsd.org/~peter/svn_notes.txt</link>,
work that is intended to be merged back into HEAD should be
- in <filename>base/projects/</filename>.
- If you are doing work that is beneficial to the &os;
- community in some way but not intended to be merged directly
- back into HEAD then the proper location is <filename>base/user/your-name/</filename>.
- <link xlink:href="http://svnweb.freebsd.org/base/projects/GUIDELINES.txt">This
+ in <filename>base/projects/</filename>. If you are doing
+ work that is beneficial to the &os; community in some way
+ but not intended to be merged directly back into HEAD then
+ the proper location is
+ <filename>base/user/your-name/</filename>. <link
+ xlink:href="http://svnweb.freebsd.org/base/projects/GUIDELINES.txt">This
page</link> contains further details.</para>
<para>To create a project branch:</para>
@@ -2112,8 +2139,8 @@ ControlPersist yes</screen>
<note>
<para>The <literal>.ent</literal>, <literal>.xml</literal>,
and <literal>.xml</literal> files listed below exist in the
- &os; Documentation Project SVN repository at
- <systemitem class="fqdomainname">svn.FreeBSD.org/doc/</systemitem>.</para>
+ &os; Documentation Project SVN repository at <systemitem
+ class="fqdomainname">svn.FreeBSD.org/doc/</systemitem>.</para>
</note>
<para>If you have been given commit rights to one or more of the
@@ -2121,6 +2148,7 @@ ControlPersist yes</screen>
<itemizedlist xml:id="commit-list">
<title>Steps for New Committers</title>
+
<listitem>
<para>Add your author entity to
<filename>head/share/xml/authors.ent</filename>; this
@@ -2152,7 +2180,8 @@ ControlPersist yes</screen>
<listitem>
<para>Add yourself to the <quote>Developers</quote> section
- of the <link xlink:href="&url.articles.contributors;/index.html">Contributors
+ of the <link
+ xlink:href="&url.articles.contributors;/index.html">Contributors
List</link>
(<filename>head/en_US.ISO8859-1/articles/contributors/contrib.committers.xml</filename>)
and remove yourself from the
@@ -2180,7 +2209,8 @@ ControlPersist yes</screen>
<para>&a.des.email; has written a shell script
(<filename>head/share/pgpkeys/addkey.sh</filename>) to
- make this extremely simple. See the <link xlink:href="http://svnweb.FreeBSD.org/doc/head/share/pgpkeys/README">README</link>
+ make this extremely simple. See the <link
+ xlink:href="http://svnweb.FreeBSD.org/doc/head/share/pgpkeys/README">README</link>
file for more information.</para>
<note>
@@ -2188,8 +2218,10 @@ ControlPersist yes</screen>
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
- <systemitem class="fqdomainname">FreeBSD.org</systemitem> users is
- available for download from <link xlink:href="&url.base;/doc/pgpkeyring.txt">http://www.FreeBSD.org/doc/pgpkeyring.txt</link>.</para>
+ <systemitem
+ class="fqdomainname">FreeBSD.org</systemitem> users is
+ available for download from <link
+ xlink:href="&url.base;/doc/pgpkeyring.txt">http://www.FreeBSD.org/doc/pgpkeyring.txt</link>.</para>
</note>
</listitem>
@@ -2212,24 +2244,26 @@ ControlPersist yes</screen>
<listitem>
<para>If you already have an account at the
- <link xlink:href="http://wiki.freebsd.org">&os; wiki</link>,
- make sure your mentor moves you from the <link xlink:href="http://wiki.freebsd.org/ContributorsGroup">Contributors
- group</link> to the <link xlink:href="http://wiki.freebsd.org/DevelopersGroup">Developers
- group</link>. Otherwise, consider signing up for an
+ <link xlink:href="http://wiki.freebsd.org">&os;
+ wiki</link>, make sure your mentor moves you from the
+ <link
+ xlink:href="http://wiki.freebsd.org/ContributorsGroup">Contributors
+ group</link> to the <link
+ xlink:href="http://wiki.freebsd.org/DevelopersGroup">Developers
+ group</link>. 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
- <link xlink:href="http://wiki.freebsd.org/HowWeGotHere">How We
+ to the <link
+ xlink:href="http://wiki.freebsd.org/HowWeGotHere">How We
Got Here</link>,
<link xlink:href="http://wiki.freebsd.org/IrcNicks">Irc
- Nicks</link>, and
- <link
- xlink:href="https://wiki.freebsd.org/DogsOfFreeBSD">Dogs
- of FreeBSD</link> pages.</para>
+ Nicks</link>, and <link
+ xlink:href="https://wiki.freebsd.org/DogsOfFreeBSD">Dogs
+ of FreeBSD</link> pages.</para>
</listitem>
<listitem>
@@ -2266,18 +2300,19 @@ ControlPersist yes</screen>
</listitem>
<listitem>
- <para>Log into <systemitem>hub.FreeBSD.org</systemitem> and create a
- <filename>/var/forward/user</filename>
- (where <replaceable>user</replaceable> is your username)
- file containing the e-mail address where you want mail
+ <para>Log into <systemitem>hub.FreeBSD.org</systemitem> and
+ create a <filename>/var/forward/user</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 <systemitem>hub</systemitem> often
- get <quote>accidentally</quote> truncated without warning,
- so forward it or read it and you will not lose it.</para>
+ taken up permanent residence on
+ <systemitem>hub</systemitem> 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
@@ -2288,9 +2323,9 @@ ControlPersist yes</screen>
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
- <systemitem class="fqdomainname">freefall.FreeBSD.org</systemitem> to
- disable the checks for your email.</para>
+ directory on <systemitem
+ class="fqdomainname">freefall.FreeBSD.org</systemitem>
+ to disable the checks for your email.</para>
</listitem>
</itemizedlist>
@@ -2328,201 +2363,199 @@ ControlPersist yes</screen>
<para>This section contains some suggestions and traditions for
how commit logs are formatted.</para>
- <para>As well as including an informative message with each
- commit you may need to include some 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>
-
- <informaltable frame="none" pgwide="1">
- <tgroup cols="2">
- <tbody>
- <row>
- <entry><literal>PR:</literal></entry>
- <entry>The problem report (if any) which is affected
- (typically, by being closed) by this
- commit. Only include one PR per line as the
- automated scripts which parse this line can not
- understand more than one.</entry>
- </row>
-
- <row>
- <entry><literal>Submitted by:</literal></entry>
- <entry><para>The name and e-mail address of the person
- that submitted the fix; for developers, just the
- username on the &os; cluster.</para>
- <para>If the submitter is the maintainer of the port
- to which you are commiting include "(maintainer)"
- after the email address.</para>
- <para>Avoid obfuscating the
- email address of the submitter as this adds
- additional work when searching logs.</para>
- </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 developers,
- just the username on the &os; 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><para>The name and e-mail address of the person or
- people that approved the change; for developers,
- just the username on the &os; 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.</para>
-
- <para>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>''.</para>
-
- <para>If a team approved these commits
- then include the team
- name followed by the username of the approver in
- parentheses. For example: ``<replaceable>re@
- (username)</replaceable>``</para></entry>
- </row>
-
- <row>
- <entry><literal>Obtained from:</literal></entry>
- <entry>The name of the project (if any) from which
- the code was obtained. Do not use this line for the
- name of an individual person.</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>
- </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
- issue. If possible, include a VuXML URL or a CVE ID.</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- <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>As well as including an informative message with each
+ commit you may need to include some 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>
+
+ <informaltable frame="none" pgwide="1">
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry><literal>PR:</literal></entry>
+ <entry>The problem report (if any) which is affected
+ (typically, by being closed) by this commit. Only
+ include one PR per line as the automated scripts which
+ parse this line can not understand more than
+ one.</entry>
+ </row>
+
+ <row>
+ <entry><literal>Submitted by:</literal></entry>
+ <entry>
+ <para>The name and e-mail address of the person
+ that submitted the fix; for developers, just the
+ username on the &os; cluster.</para>
+
+ <para>If the submitter is the maintainer of the port
+ to which you are commiting include "(maintainer)"
+ after the email address.</para>
+
+ <para>Avoid obfuscating the email address of the
+ submitter as this adds additional work when searching
+ logs.</para>
+ </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 developers,
+ just the username on the &os; 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><para>The name and e-mail address of the person or
+ people that approved the change; for developers, just
+ the username on the &os; 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.</para>
+
+ <para>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>''.</para>
+
+ <para>If a team approved these commits then include the
+ team name followed by the username of the approver in
+ parentheses. For example: ``<replaceable>re@
+ (username)</replaceable>``</para></entry>
+ </row>
+
+ <row>
+ <entry><literal>Obtained from:</literal></entry>
+ <entry>The name of the project (if any) from which
+ the code was obtained. Do not use this line for the
+ name of an individual person.</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>
+ </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 issue. If possible,
+ include a VuXML URL or a CVE ID.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <example>
+ <title>Commit Log for a Commit Based on a PR</title>
- <programlisting>...
+ <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>...
PR: foo/12345
Submitted by: John Smith <John.Smith at example.com></programlisting>
- </example>
+ </example>
- <example>
- <title>Commit Log for a Commit Needing Review</title>
+ <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>...
+ <programlisting>...
Reviewed by: -arch</programlisting>
- </example>
+ </example>
- <example>
- <title>Commit Log for a Commit Needing Approval</title>
+ <example>
+ <title>Commit Log for a Commit Needing Approval</title>
- <para>You want to commit a port
- You have collaborated with
- the listed MAINTAINER, who has told you to go ahead and
- commit.</para>
+ <para>You want to commit a port You have collaborated with
+ the listed MAINTAINER, who has told you to go ahead and
+ commit.</para>
- <programlisting>...
+ <programlisting>...
Approved by: <replaceable>abc</replaceable> (maintainer)</programlisting>
- <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>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>...
+ <programlisting>...
Obtained from: OpenBSD</programlisting>
- </example>
+ </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>
- <example>
- <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
- weeks.</para>
+ <para>You want to commit some code which will be merged from
+ &os.current; into the &os.stable; branch after two
+ weeks.</para>
- <programlisting>...
+ <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
- <literal>day</literal>, <literal>days</literal>,
- <literal>week</literal>, <literal>weeks</literal>,
- <literal>month</literal>,
- <literal>months</literal>.</para>
- </example>
-
- <para>In many 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>
-
- <para>The extra information to include in the commit would
- look something like</para>
- <example>
- <title>Example Combined Commit Log</title>
- <programlisting>PR: foo/54321
+ <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>.</para>
+ </example>
+
+ <para>In many 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>
+
+ <para>The extra information to include in the commit would look
+ something like</para>
+
+ <example>
+ <title>Example Combined Commit Log</title>
+
+ <programlisting>PR: foo/54321
Submitted by: John Smith <John.Smith at example.com>
Reviewed by: -arch
Obtained from: NetBSD
MFC after: 1 month</programlisting>
-</example>
+ </example>
</sect1>
<sect1 xml:id="pref-license">
@@ -2601,31 +2634,31 @@ MFC after: 1 month</programlist
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
*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
More information about the svn-doc-all
mailing list