Date: Sun, 30 Jun 2013 01:00:51 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r42087 - head/en_US.ISO8859-1/articles/committers-guide Message-ID: <201306300100.r5U10pVY081623@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: wblock Date: Sun Jun 30 01:00:50 2013 New Revision: 42087 URL: http://svnweb.freebsd.org/changeset/doc/42087 Log: Whitespace-only changes. 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 Sat Jun 29 22:59:48 2013 (r42086) +++ head/en_US.ISO8859-1/articles/committers-guide/article.xml Sun Jun 30 01:00:50 2013 (r42087) @@ -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> + 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> + 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> - - <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> - - <note> - <para>Do not forget to get mentor approval for these patches!</para> - </note> - - </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> + <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> + + <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> + </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>Also add your author entity to + <filename>head/share/xml/developers.ent</filename>.</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>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> - <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> + <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> - <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>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> + + <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> - - <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> + <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 *** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201306300100.r5U10pVY081623>