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

* add SVN branches analogous to the "Noteworthy CVS Tags"

Browse source 
* don't use RELENG_5 anymore
* don't mention CVS explicitly when the text applies to any version control system
* introduce Subversion (pointers and its usage in the src tree)
* don't mention ncvs as a CVS commit host anymore
* replace all sys/*fs examples in the practical CVS primer by analogous ports/Tools examples
* use ISO yyyy-mm-dd date format for -D flag of cvs
* mention that Subversion stores metadata in .svn directories
* remove text concerning the -j flag of cvs
* mention svn-committers and that it is a normal read/write list
* remove most of q&a 16.2, point to SubversionPrimer/Merging on the wiki instead

Reviewed by:	trhodes, gabor, keramida
Approved by:	keramida
This commit is contained in:
Rene Ladan 2009-04-05 18:51:11 +00:00
parent ef332c8084
commit e2718a3657
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=34044
1 changed files with 114 additions and 171 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

285
en_US.ISO8859-1/articles/committers-guide/article.sgml
View file

@ -72,7 +72,7 @@
<row>
<entry><emphasis>Main CVSROOT</emphasis></entry>
<entry>
<hostid role="fqdn">ncvs.FreeBSD.org</hostid><literal>:</literal><filename>/home/ncvs</filename> (although also see <xref linkend="cvs.operations">).
<hostid role="fqdn">ncvs.FreeBSD.org</hostid><literal>:</literal><filename>/home/ncvs</filename> (although also see <xref linkend="vcs.operations">).
</entry>
</row>
@ -111,13 +111,23 @@
</row>
<row>
<entry><emphasis>Noteworthy CVS Tags</emphasis></entry>
<entry><literal>RELENG_5</literal> (5.X-STABLE),
<entry><emphasis>Noteworthy CVSup Tags</emphasis></entry>
<entry>
<literal>RELENG_6</literal> (6.X-STABLE),
<literal>RELENG_7</literal> (7.X-STABLE),
<literal>HEAD</literal> (-CURRENT)
</entry>
</row>
<row>
<entry><emphasis>Noteworthy SVN Branches</emphasis></entry>
<entry>
<literal>stable/6</literal> (6.X-STABLE),
<literal>stable/7</literal> (7.X-STABLE),
<literal>head</literal> (-CURRENT)
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
@ -137,7 +147,7 @@
<sect1 id="committer.types">
<title>Commit Bit Types</title>
<para>The FreeBSD CVS repository has a number of components which,
<para>The FreeBSD 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 FreeBSD commit bits are
@ -225,20 +235,21 @@
</sect1>
<sect1 id="cvs.operations">
<title>CVS Operations</title>
<sect1 id="vcs.operations">
<title>Version Control System Operations</title>
<para>It is assumed that you are already familiar with the basic operation
of CVS.</para>
of the version control systems in use. Traditionally this was
CVS, but as of June 2008, Subversion is used for the src tree.</para>
<para>The &a.cvsadm; are the <quote>owners</quote> of the CVS repository and
<para>The &a.cvsadm; are the <quote>owners</quote> of the repository and
are responsible for direct modification of it for the purposes of
cleanup or fixing some grievous abuse of CVS by a committer.
Should you cause some repository accident, say a bad <command>cvs
import</command> or <command>cvs tag</command> operation, mail the
cleanup or fixing some unfortunate abuse of the version control system by a committer.
Should you cause some repository accident, say a bad
import or a bad tag creation, mail the
responsible part of &a.cvsadm;, as stated in the table below,
(or call one of them) and report the problem.
For very important issues affecting the entire CVS tree&mdash;not
For very important issues affecting the entire tree&mdash;not
just a specific area&mdash;you can contact the &a.cvsadm;.
Please do <emphasis>not</emphasis> contact the &a.cvsadm; for repocopies
or other things that the more specific teams can handle.</para>
@ -248,16 +259,12 @@
no login shells available on the repository machines, except to
the repomeisters.</para>
<note><para>Depending on the affected area of the CVS repository,
<note><para>Depending on the affected area of the repository,
you should send your request for a repocopy to one of the following email
addresses. Email sent to these addresses will be forwarded
to the appropriate repomeisters.</para>
<itemizedlist>
<listitem><para>ncvs@ - regarding <filename class="directory">
/home/ncvs</filename>, the src
repository</para></listitem>
<listitem><para>pcvs@ - regarding <filename class="directory">
/home/pcvs</filename>, the ports
repository</para></listitem>
@ -272,11 +279,17 @@
</itemizedlist>
</note>
<para>The CVS tree is currently split into four distinct repositories,
<para>The &os; repositories are currently split into four distinct parts,
namely <literal>doc</literal>, <literal>ports</literal>,
<literal>projects</literal> and <literal>src</literal>. These are
combined under a single <literal>CVSROOT</literal> when distributed
via <application>CVSup</application> for the convenience of our users.</para>
via <application>CVSup</application> for the convenience of our users.
The <literal>src</literal> tree is automatically exported to
CVS for compatibility reasons only (e.g.
<application>CVSup</application>). The <quote>official</quote>
<literal>src</literal> repository is not stored in
<application>CVS</application> but in Subversion. The official
and exported trees are not necessarily equal.</para>
<note><para>Note that the <literal>www</literal> module containing sources
for the <ulink url="http://www.FreeBSD.org">FreeBSD website</ulink> is
@ -320,12 +333,6 @@
<entry>projcvs.FreeBSD.org</entry>
<entry>/home/projcvs</entry>
</row>
<row>
<entry>src</entry>
<entry>ncvs.FreeBSD.org</entry>
<entry>/home/ncvs</entry>
</row>
</tbody>
</tgroup>
</table>
@ -333,7 +340,7 @@
<para>CVS operations are done remotely by setting the
<envar>CVSROOT</envar> environment variable to the appropriate host
and top-level directory (for example,
<hostid role="fqdn">ncvs.FreeBSD.org</hostid><literal>:</literal><filename>/home/ncvs</filename>),
<hostid role="fqdn">dcvs.FreeBSD.org</hostid><literal>:</literal><filename>/home/dcvs</filename>),
and
doing the appropriate check-out/check-in operations. Many committers
define aliases which expand to the correct <application>cvs</application>
@ -343,14 +350,11 @@
<programlisting>alias dcvs cvs -d <replaceable>user</replaceable>@dcvs.FreeBSD.org:/home/dcvs
alias pcvs cvs -d <replaceable>user</replaceable>@pcvs.FreeBSD.org:/home/pcvs
alias projcvs cvs -d <replaceable>user</replaceable>@projcvs.FreeBSD.org:/home/projcvs
alias scvs cvs -d <replaceable>user</replaceable>@ncvs.FreeBSD.org:/home/ncvs</programlisting>
alias projcvs cvs -d <replaceable>user</replaceable>@projcvs.FreeBSD.org:/home/projcvs</programlisting>
<para>This way they can do all CVS operations
locally and use <command><replaceable>X</replaceable>cvs commit</command> for committing
to the official CVS tree. If you wish to add
something which is wholly new (like contrib-ified
sources, etc), <command>cvs import</command> should be used.
to the official CVS repository.
Refer to the &man.cvs.1; manual page for usage.</para>
<note>
@ -381,7 +385,7 @@ alias scvs cvs -d <replaceable>user</replaceable>@ncvs.FreeBSD.org:/home/ncvs</p
to their new name and/or location and let you know when it is
done. The purpose of a repository copy is to preserve file
change history, or logs. We in the FreeBSD Project greatly
value the change history that CVS gives to the project.</para>
value the change history that a version control system gives to the project.</para>
<para>CVS reference information, tutorials, and FAQs can be found at:
<ulink url="http://www.cvshome.org/docs/"></ulink>.
@ -437,96 +441,73 @@ alias scvs cvs -d <replaceable>user</replaceable>@ncvs.FreeBSD.org:/home/ncvs</p
<itemizedlist>
<listitem>
<para>Check out the <filename>miscfs</filename> module,
which corresponds to <filename>src/sys/miscfs</filename>:</para>
<para>Check out the <filename>Tools</filename> module,
which corresponds to <filename>ports/Tools</filename>:</para>
<screen>&prompt.user; <userinput>cvs co miscfs</userinput></screen>
<screen>&prompt.user; <userinput>cvs co Tools</userinput></screen>
<para>You now have a directory named <filename>miscfs</filename>
with subdirectories <filename>CVS</filename>,
<filename>deadfs</filename>, <filename>devfs</filename>, and so
on. One of these (<filename>linprocfs</filename>) is
empty.</para>
<para>You now have a directory named <filename>ports/Tools</filename>
with subdirectories <filename>portbuild</filename>,
<filename>scripts</filename>, and
<filename>CVS</filename>.</para>
</listitem>
<listitem>
<para>Check out the same files, but with full path:</para>
<screen>&prompt.user; <userinput>cvs co src/sys/miscfs</userinput></screen>
<para>You now have a directory named <filename>src</filename>,
<screen>&prompt.user; <userinput>cvs co ports/Tools</userinput></screen>
<para>You now have a directory named <filename>ports</filename>,
with subdirectories <filename>CVS</filename> and
<filename>sys</filename>. The <filename>src/sys</filename> directory has
<filename>Tools</filename>. The <filename>ports/Tools</filename> directory has
subdirectories <filename>CVS</filename> and
<filename>miscfs</filename>, etc.</para>
<filename>scripts</filename>, etc.</para>
</listitem>
<listitem>
<para>Check out the same files, but prunes empty
directories:</para>
<screen>&prompt.user; <userinput>cvs co -P miscfs</userinput></screen>
<para>You now have a directory named
<filename>miscfs</filename> with subdirectories
<filename>CVS</filename>, <filename>deadfs</filename>,
<filename>devfs</filename>... but note that there is no
<filename>linprocfs</filename> subdirectory, because there
are no files in it.</para>
</listitem>
<listitem>
<para>Check out the directory <filename>miscfs</filename>, but
<para>Check out the directory <filename>Tools</filename>, but
none of the subdirectories:</para>
<screen>&prompt.user; <userinput>cvs co -l miscfs</userinput></screen>
<screen>&prompt.user; <userinput>cvs co -l Tools</userinput></screen>
<para>You now have a directory named <filename>miscfs</filename>
<para>You now have a directory named <filename>Tools</filename>
with just one subdirectory named
<filename>CVS</filename>.</para>
</listitem>
<listitem>
<para>Check out the <filename>miscfs</filename> module as
it is in the 6.X branch:</para>
<para>Check out the <filename>Tools</filename> module as
it was when support for &os;&nbsp;5.X was dropped:</para>
<screen>&prompt.user; <userinput>cvs co -rRELENG_6 miscfs</userinput></screen>
<para>You can modify the sources and commit along this
branch.</para>
</listitem>
<listitem>
<para>Check out the <filename>miscfs</filename> module as
it was in 6.0-RELEASE.</para>
<screen>&prompt.user; <userinput>cvs co -rRELENG_6_0_0_RELEASE miscfs</userinput></screen>
<screen>&prompt.user; <userinput>cvs co -rRELEASE_5_EOL Tools</userinput></screen>
<para>You will not be able to commit modifications, since
<literal>RELENG_6_0_0_RELEASE</literal> is a point in time, not a branch.</para>
<literal>RELEASE_5_EOL</literal> is a point in time, not a branch.</para>
</listitem>
<listitem>
<para>Check out the <filename>miscfs</filename> module as it was
on Jan 15 2000.</para>
<para>Check out the <filename>Tools</filename> module as it was
on March 25th, 2009:</para>
<screen>&prompt.user; <userinput>cvs co -D'01/15/2000' miscfs</userinput></screen>
<screen>&prompt.user; <userinput>cvs co -D'2009-03-25' Tools</userinput></screen>
<para>You will not be able to commit modifications.</para>
</listitem>
<listitem>
<para>Check out the <filename>miscfs</filename> module as it was
one week ago.</para>
<para>Check out the <filename>Tools</filename> module as it was
one week ago:</para>
<screen>&prompt.user; <userinput>cvs co -D'last week' miscfs</userinput></screen>
<screen>&prompt.user; <userinput>cvs co -D'last week' Tools</userinput></screen>
<para>You will not be able to commit modifications.</para>
</listitem>
</itemizedlist>
<para>Note that cvs stores metadata in subdirectories named
<filename>CVS</filename>.</para>
<filename>CVS</filename>.
Similarly, Subversion stores metadata in subdirectories named
<filename>.svn</filename>.</para>
<para>Arguments to <option>-D</option> and <option>-r</option>
are sticky, which means cvs will remember them later, e.g.
@ -594,7 +575,7 @@ alias scvs cvs -d <replaceable>user</replaceable>@ncvs.FreeBSD.org:/home/ncvs</p
<para>This updates the file <filename>shazam</filename> or the
contents of the <filename>shazam</filename> directory to the
latest version along the branch you checked out. If you
checked out a <quote>point in time</quote>, does nothing
checked out a <quote>point in time</quote>, it does nothing
unless the tags have moved in the repository or some other weird
stuff is going on.</para>
@ -613,11 +594,6 @@ alias scvs cvs -d <replaceable>user</replaceable>@ncvs.FreeBSD.org:/home/ncvs</p
<entry><option>-A</option></entry>
<entry>Update to head of main branch.</entry>
</row>
<row>
<entry><option>-j<replaceable>rev</replaceable></option></entry>
<entry>More magic (see below).</entry>
</row>
</tbody>
</tgroup>
</informaltable>
@ -718,41 +694,6 @@ alias scvs cvs -d <replaceable>user</replaceable>@ncvs.FreeBSD.org:/home/ncvs</p
repository version, followed by a marker line with seven
<literal>&gt;</literal> signs and the revision number you
updated to.</para>
<para>The <option>-j</option> option is slightly voodoo. It
updates the local file to the specified revision as if you
used <option>-r</option>, but it does not change the recorded
revision number or branch of the local file. It is not really
useful except when used twice, in which case it will merge the
changes between the two specified versions into the working
copy.</para>
<para>For instance, say you commit a change to
<filename>shazam/shazam.c</filename> in &os.current; and later
want to MFC it. The change you want to MFC was revision
1.15:</para>
<itemizedlist>
<listitem>
<para>Check out the &os.stable; version of the
<filename>shazam</filename> module:</para>
<screen>&prompt.user; <userinput>cvs co -rRELENG_6 shazam</userinput></screen>
</listitem>
<listitem>
<para>Apply the changes between rev 1.14 and 1.15:</para>
<screen>&prompt.user; <userinput>cvs update -j1.14 -j1.15 shazam/shazam.c</userinput></screen>
</listitem>
</itemizedlist>
<para>You will almost certainly get a conflict because
of the <literal>$Id: article.sgml,v 1.282 2009-04-05 18:30:41 rene Exp $</literal> (or in FreeBSD's case,
<literal>$<!-- stop expansion -->FreeBSD<!-- stop expansion -->$</literal>)
lines, so you will have to edit the file to resolve the conflict
(remove the marker lines and the second <literal>$Id: article.sgml,v 1.282 2009-04-05 18:30:41 rene Exp $</literal> line,
leaving the original <literal>$Id: article.sgml,v 1.282 2009-04-05 18:30:41 rene Exp $</literal> line intact).</para>
</listitem>
<listitem>
@ -899,8 +840,25 @@ alias scvs cvs -d <replaceable>user</replaceable>@ncvs.FreeBSD.org:/home/ncvs</p
</tgroup>
</table>
<para>Use the <option>-f</option> option if you realize that
you left out important information from the commit message.</para>
<para>The following are some Subversion examples related to the
src repository. More (in-depth) information can be found at
<ulink
url="http://wiki.freebsd.org/SubversionPrimer">Subversion
Primer</ulink> and <ulink
url="http://wiki.freebsd.org/SubversionMissing">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. Subversion is also described in-depth
in <ulink url="http://svnbook-red-bean.com/">Version Control with Subversion</ulink>.</para>
<itemizedlist>
<listitem>
<para>Check out the <literal>head</literal> branch:</para>
<screen>&prompt.user; <userinput>svn co svn+ssh://svn.freebsd.org/base/head /usr/src</userinput></screen>
</listitem>
</itemizedlist>
<para>Good commit messages are important. They tell others
why you did the changes you did, not just right here and now,
@ -938,19 +896,19 @@ alias scvs cvs -d <replaceable>user</replaceable>@ncvs.FreeBSD.org:/home/ncvs</p
<itemizedlist>
<listitem>
<para>verify which branch you are committing to, using
<command>cvs status</command>.</para>
<command>svn status</command>. This is only needed for
the src tree, as the other trees are not branched.</para>
</listitem>
<listitem>
<para>review your diffs, using
<command>cvs diff</command></para>
<para>review your diffs, using the diff command of the version control system.</para>
</listitem>
</itemizedlist>
<para>Also, ALWAYS specify which files to commit explicitly on
the command line, so you do not accidentally commit other files
than the ones you intended - <command>cvs commit</command>
without any arguments will commit every modification in your
than the ones you intended &mdash; a commit operation
without any arguments usually will commit every modification in your
current working directory and every subdirectory.</para>
</listitem>
</orderedlist>
@ -1055,9 +1013,7 @@ checkout -P</programlisting>
ssh connection to the repository machine. First, put this
configuration into your <filename>~/.ssh/config</filename>:</para>
<programlisting>Host ncvs.FreeBSD.org
ControlPath /home/<replaceable>user</replaceable>/.ssh/cvs.cpath
Host dcvs.FreeBSD.org
<programlisting>Host dcvs.FreeBSD.org
ControlPath /home/<replaceable>user</replaceable>/.ssh/cvs.cpath
Host projcvs.FreeBSD.org
ControlPath /home/<replaceable>user</replaceable>/.ssh/cvs.cpath
@ -1322,14 +1278,14 @@ Host pcvs.FreeBSD.org
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>cvs-committers</literal> mailing list that you can
<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 output of <command>cvs log</command>
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
@ -1343,10 +1299,10 @@ Host pcvs.FreeBSD.org
<para>If you are unsure about a commit for any reason at
all, have it reviewed by <literal>-hackers</literal>
before committing. Better to have it flamed then and there
rather than when it is part of the CVS repository. If you do
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 &ndash; with CVS we
again until the matter is settled. Remember &ndash; with a version control system we
can always change it back.</para>
<para>Do not impugn the intentions of someone you disagree with.
@ -1624,10 +1580,14 @@ docs:Documentation Bug:freebsd-doc:</programlisting>
<term>&a.committers;</term>
<listitem>
<para>cvs-committers is the entity that CVS uses to send you all your
<para>cvs-committers is the entity that the version control system uses to send you all your
commit messages. You should <emphasis>never</emphasis> send email
directly to this list. You should only send replies to this list
when they are short and are directly related to a commit.</para>
<para>There is a similar list, svn-committers, which has a
similar purpose but is a normal list, i.e. you are free to
send any suitable message to this list.</para>
</listitem>
</varlistentry>
@ -1973,7 +1933,7 @@ docs:Documentation Bug:freebsd-doc:</programlisting>
<para>Discuss any significant change
<emphasis>before</emphasis> committing.</para>
<para>The CVS repository is not where changes should be
<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
@ -2010,7 +1970,7 @@ docs:Documentation Bug:freebsd-doc:</programlisting>
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 CVS logs for the file(s) in
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>
@ -2032,7 +1992,7 @@ docs:Documentation Bug:freebsd-doc:</programlisting>
<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 CVS makes it unnecessary to have an ongoing
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
@ -2262,7 +2222,7 @@ docs:Documentation Bug:freebsd-doc:</programlisting>
<para>Do not mix style fixes with new functionality. A style
fix is any change which does not modify the functionality of
the code. Mixing the changes obfuscates the functionality
change when using <command>cvs diff</command>, which can hide
change when asking for differences between revisions, which can hide
any new bugs. Do not include whitespace changes with content
changes in commits to <filename>doc/</filename> or
<filename>www/</filename>. The extra clutter in the diffs
@ -3236,7 +3196,7 @@ bak/packages packages from last complete &lt;major_version&gt; run on &lt;arch&
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 CVS commits and the mailing list
well (except things specific to commits and the mailing list
memberships that go with them). In particular, we recommend that
you read:</para>
@ -3354,39 +3314,22 @@ bak/packages packages from last complete &lt;major_version&gt; run on &lt;arch&
<qandaentry>
<question>
<para>How do I add a new file to a CVS branch?</para>
<para>How do I add a new file to a branch?</para>
</question>
<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
<command>cvs add</command> as you normally would. For
example, if you wanted to MFC the file
<filename>src/sys/alpha/include/smp.h</filename> from HEAD
to RELENG_6 and it does not exist in RELENG_6 yet, you would
use the following steps:</para>
<example>
<title>MFC'ing a New File</title>
<screen>&prompt.user; <userinput>cd sys/alpha/include</userinput>
&prompt.user; <userinput>cvs update -rRELENG_6</userinput>
cvs update: Updating .
U clockvar.h
U console.h
...
&prompt.user; <userinput>cvs update -kk -Ap smp.h &gt; smp.h</userinput>
===================================================================
Checking out smp.h
RCS: /usr/cvs/src/sys/alpha/include/smp.h,v
VERS: 1.1
***************
&prompt.user; <userinput>cvs add smp.h</userinput>
cvs add: scheduling file `smp.h' for addition on branch `RELENG_6'
cvs add: use 'cvs commit' to add this file permanently
&prompt.user; <userinput>cvs commit</userinput>
</screen>
</example>
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>