2003 lines
77 KiB
Text
2003 lines
77 KiB
Text
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" [
|
|
<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
|
|
%man;
|
|
|
|
<!ENTITY % authors PUBLIC "-//FreeBSD//ENTITIES DocBook Author Entities//EN">
|
|
%authors;
|
|
]>
|
|
|
|
<article>
|
|
<artheader>
|
|
<title>Committer Guide</title>
|
|
|
|
<authorgroup>
|
|
<author>
|
|
<surname>The FreeBSD Documentation Project</surname>
|
|
</author>
|
|
</authorgroup>
|
|
|
|
<pubdate>$FreeBSD: doc/en_US.ISO_8859-1/articles/committers-guide/article.sgml,v 1.36 2000/08/23 20:36:53 ben Exp $</pubdate>
|
|
|
|
<copyright>
|
|
<year>1999</year>
|
|
<year>2000</year>
|
|
<holder>The FreeBSD Documentation Project</holder>
|
|
</copyright>
|
|
|
|
<abstract>
|
|
<para>This document provides information for the FreeBSD committer
|
|
community. All new committers should read this document before they
|
|
start, and existing committers are strongly encouraged to review it
|
|
from time to time.</para>
|
|
</abstract>
|
|
</artheader>
|
|
|
|
<sect1 id="admin">
|
|
<title>Administrative Details</title>
|
|
|
|
<informaltable frame="none" orient="port">
|
|
<tgroup cols="2">
|
|
<tbody>
|
|
<row>
|
|
<entry><emphasis>Main Repository Host</emphasis></entry>
|
|
<entry><hostid>freefall.FreeBSD.org</hostid></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><emphasis>Login Methods</emphasis></entry>
|
|
<entry>&man.ssh.1;</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><emphasis>Main CVSROOT</emphasis></entry>
|
|
<entry>/home/ncvs</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><emphasis>Main CVS Repository Meisters</emphasis></entry>
|
|
<entry>&a.jdp; and &a.peter; as well as &a.asami; for
|
|
<filename>ports/</filename></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><emphasis>Mailing List</emphasis></entry>
|
|
<entry><email>cvs-committers@FreeBSD.org</email></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><emphasis>Noteworthy CVS Tags</emphasis></entry>
|
|
<entry>RELENG_3 (3.x-STABLE), RELENG_4 (4.x-STABLE), HEAD (-CURRENT)</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>It is required that you use &man.ssh.1; or &man.telnet.1;
|
|
with Kerberos 5 to connect to the repository hosts. These are
|
|
generally more secure than plain &man.telnet.1; or
|
|
&man.rlogin.1; since credential negotiation will always be
|
|
encrypted. All traffic is encrypted by default with &man.ssh.1;.
|
|
With utilities like &man.ssh-agent.1; and &man.scp.1; also
|
|
available, &man.ssh.1; is also far more convenient. If you do
|
|
not know anything about &man.ssh.1;, please see
|
|
<xref linkend="ssh.guide">.</para>
|
|
</sect1>
|
|
|
|
<sect1 id="cvs.operations">
|
|
<title>CVS Operations</title>
|
|
|
|
<para>It is assumed that you are already familiar with the basic operation
|
|
of CVS.</para>
|
|
|
|
<para>The CVS Repository Meisters (Peter Wemm and John Polstra)
|
|
are the <quote>owners</quote> of the CVS repository and are
|
|
responsible for any and <emphasis>all</emphasis> direct
|
|
modification of it for the purposes of cleanup or fixing some
|
|
grievous abuse of CVS by a committer. No one else should
|
|
attempt to touch the repository directly. Should you cause some
|
|
repository accident, say a bad cvs import or tag operation, do
|
|
<emphasis role="bold">not</emphasis> attempt to fix it yourself!
|
|
Mail or call John or Peter immediately and report the problem to
|
|
one of them instead. The only ones allowed to directly fiddle
|
|
the repository bits are the repomeisters. Satoshi Asami is also a
|
|
repomeister for the <filename>ports/</filename> portion of the
|
|
tree.</para>
|
|
|
|
<para>CVS operations are usually done by logging into
|
|
<hostid>freefall</hostid>, making sure the
|
|
<envar>CVSROOT</envar> environment variable is set to
|
|
<filename>/home/ncvs</filename>, and then doing the appropriate
|
|
check-out/check-in operations. If you wish to add
|
|
something which is wholly new (like contrib-ified
|
|
sources, etc), a script called <quote>easy-import</quote> is
|
|
also provided for making the process easier. It automatically
|
|
adds the new module entry, does the appropriate thing with
|
|
<command>cvs import</command>, etc. – just run it without
|
|
arguments and it will prompt you for everything it needs to
|
|
know.</para>
|
|
|
|
<para>Note that when you use CVS on <hostid>freefall</hostid>, you
|
|
should set your <literal>umask</literal> to <literal>2</literal>,
|
|
as well as setting the <literal>CVSUMASK</literal> environmenet
|
|
variable to <literal>2</literal>. This ensures that any new
|
|
files created by <command>cvs add</command> will have the correct
|
|
permissions. If you add a file or directory and discover that the
|
|
file in the repository has incorrect permissions (specifically,
|
|
all files in the repository should be group writable by group
|
|
<literal>ncvs</literal>), contact one of the repository meisters
|
|
as described below.</para>
|
|
|
|
<para>If you are familiar with remote CVS and consider yourself
|
|
pretty studly with CVS in general, you can also do CVS
|
|
operations directly from your own machine and local working
|
|
sources. Just remember to set <envar>CVS_RSH</envar> to
|
|
<wordasword>ssh</wordasword> so that you are using a relatively
|
|
secure and reliable transport. If you have no idea what any of
|
|
the above even means, on the other hand, then please stick with
|
|
logging into <hostid>freefall</hostid> and applying your diffs
|
|
with &man.patch.1;.</para>
|
|
|
|
<para>If you need to use CVS <command>add</command> and
|
|
<command>delete</command> operations in a manner that is
|
|
effectively a <quote>mv</quote> operation, then a repository
|
|
copy is in order rather than your CVS <command>add</command> and
|
|
<command>delete</command>. In a repository copy, a <link
|
|
linkend="conventions">CVS Meister</link> will copy the file(s)
|
|
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 CVS gives to the project.</para>
|
|
|
|
<para>CVS reference information, tutorials, and FAQs can also be found at:
|
|
<ulink
|
|
url="http://www.cyclic.com/CVS/support">http://www.cyclic.com/CVS/support</ulink></para>
|
|
|
|
<para>&a.des; also supplied the following <quote>mini primer</quote> for
|
|
CVS.</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Check out a module with the <literal>co</literal> or
|
|
<literal>checkout</literal> command.</para>
|
|
|
|
<screen>&prompt.user; <userinput>cvs checkout shazam</userinput></screen>
|
|
|
|
<para>This checks out a copy of the <filename>shazam</filename> module. If
|
|
there is no <filename>shazam</filename> module in the modules file, looks for a
|
|
top-level directory named <filename>shazam</filename> instead.</para>
|
|
|
|
<para>Useful options:</para>
|
|
|
|
<informaltable>
|
|
<tgroup cols=2>
|
|
<tbody>
|
|
<row>
|
|
<entry><option>-P</option></entry>
|
|
<entry>Don't create empty directories</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><option>-l</option></entry>
|
|
<entry>Check out a single level, no subdirectories</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><option>-r<replaceable>rev</replaceable></option></entry>
|
|
<entry>Check out revision, branch or tag
|
|
<replaceable>rev</replaceable></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><option>-D<replaceable>date</replaceable></option></entry>
|
|
<entry>Check out the sources as they were on date
|
|
<replaceable>data</replaceable></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>Practical FreeBSD examples:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Check out the <filename>miscfs</filename> module,
|
|
which corresponds to <filename>src/sys/miscfs</filename>:</para>
|
|
|
|
<screen>&prompt.user; <userinput>cvs co miscfs</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>
|
|
</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>,
|
|
with subdirectories <filename>CVS</filename> and
|
|
<filename>sys</filename>. <filename>src/sys</filename> has
|
|
subdirectories <filename>CVS</filename> and
|
|
<filename>miscfs</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
|
|
none of the subdirectories:</para>
|
|
|
|
<screen>&prompt.root; <userinput>cvs co -l miscfs</userinput></screen>
|
|
|
|
<para>You now have a directory named <filename>miscfs</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 4.x branch:</para>
|
|
|
|
<screen>&prompt.user; <userinput>cvs co -rRELENG_4 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 3.4-RELEASE.</para>
|
|
|
|
<screen>&prompt.user; <userinput>cvs co -rRELENG_3_4_0_RELEASE miscfs</userinput></screen>
|
|
|
|
<para>You will not be able to commit modifications, since
|
|
RELENG_3_4_0_RELEASE 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>
|
|
|
|
<screen>&prompt.user; <userinput>cvs co -D'01/15/2000' miscfs</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 agao.</para>
|
|
|
|
<screen>&prompt.user; <userinput>cvs co -D'last week' miscfs</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>
|
|
|
|
<para>Arguments to <option>-D</option> and <option>-r</option>
|
|
are sticky, which means cvs will remember them later, e.g.
|
|
when you do a <command>cvs update</command>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Check the status of checked-out files with the
|
|
<literal>status</literal> command.</para>
|
|
|
|
<screen>&prompt.user; <userinput>cvs status shazam</userinput></screen>
|
|
|
|
<para>This displays the status of the
|
|
<filename>shazam</filename> file or of every file in the
|
|
<filename>shazam</filename> directory. For every file, the
|
|
status is given as one of:</para>
|
|
|
|
<informaltable>
|
|
<tgroup cols=2>
|
|
<tbody>
|
|
<row>
|
|
<entry>Up-to-date</entry>
|
|
<entry>File is up-to-date and unmodified.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>Needs Patch</entry>
|
|
<entry>File is unmodified, but there's a newer revision in
|
|
the repository.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>Locally Modified</entry>
|
|
<entry>File is up-to-date, but modified.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>Needs Merge</entry>
|
|
<entry>File is modified, and there's a newer revision in the
|
|
repository.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>File had conflicts on merge</entry>
|
|
<entry>There were conflicts the last time this file was
|
|
updated, and they haven't been resolved yet.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>You'll also see the local revision and date,
|
|
the revision number of the newest applicable version
|
|
(<quote>newest applicable</quote> because if you have a
|
|
sticky date, tag or branch, it may not be the actual newest
|
|
revision), and any sticky tags, dates or options.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Once you've checked something out, update it with the
|
|
<literal>update</literal> command.</para>
|
|
|
|
<screen>&prompt.user; <userinput>cvs update shazam</userinput></screen>
|
|
|
|
<para>This updates the <filename>shazam</filename> file 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
|
|
unless the tags have moved in the repo or some other weird
|
|
stuff is going on.</para>
|
|
|
|
<para>Useful options, in addition to those listed above for
|
|
<literal>checkout</literal>:</para>
|
|
|
|
<informaltable>
|
|
<tgroup cols=2>
|
|
<tbody>
|
|
<row>
|
|
<entry><option>-d</option></entry>
|
|
<entry>Check out any additional missing directories.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<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>
|
|
|
|
<para>If you checked out a module with <option>-r</option> or
|
|
<option>-D</option>, running <command>cvs update</command>
|
|
with a different <option>-r</option> or <option>-D</option>
|
|
argument or with <option>-A</option> will select a new branch,
|
|
revision or date. The <option>-A</option> option clears all
|
|
sticky tags, dates or revisions whereas <option>-r</option>
|
|
and <option>-D</option> set new ones.</para>
|
|
|
|
<para>Theoretically, specifying <literal>HEAD</literal> as
|
|
argument to <option>-r</option> will give you the same result
|
|
as <option>-A</option>, but that's just theory.</para>
|
|
|
|
<para>The <option>-d</option> option is useful if:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>somebody has added subdirectories to the module
|
|
you've checked out after you checked it out.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>you checked out with <option>-l</option>, and later
|
|
change your mind and want to check out the subdirectories
|
|
as well.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>you deleted some subdirectories and want to check
|
|
them all back out.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para><emphasis>Watch the output of the <command>cvs
|
|
update</command> with care.</emphasis> The letter in front of
|
|
each file name indicates what was done with it:</para>
|
|
|
|
<informaltable>
|
|
<tgroup cols=2>
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>U</literal></entry>
|
|
<entry>The file was updated with no trouble.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><literal>P</literal></entry>
|
|
<entry>The file was updated with no trouble (you'll only see
|
|
this when working against a remote repo).</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><literal>M</literal></entry>
|
|
<entry>The file had been modified, and was merged with no
|
|
conflicts.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><literal>C</literal></entry>
|
|
<entry>The file had been modified, and was merged with
|
|
conflicts.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>Merging is what happens if you check out a copy of
|
|
some source code, modify it, then someone else commits a
|
|
change, and you run <command>cvs update</command>. CVS notices
|
|
that you've made local changes, and tries to merge your
|
|
changes with the changes between the version you originally
|
|
checked out and the one you updated to. If the changed are to
|
|
separate portions of the file, it'll almost always work fine
|
|
(though the result might not be syntactically or semantically
|
|
correct).</para>
|
|
|
|
<para>CVS will print an 'M' in front of every locally modified
|
|
file even if there is no newer version in the repository, so
|
|
<command>cvs update</command> is handy for getting a summary
|
|
of what you've changed locally.</para>
|
|
|
|
<para>If you get a <literal>C</literal>, then your changes
|
|
conflicted with the changes in the repository (the changes
|
|
were to the same lines, or neighboring lines, or you changed
|
|
the local file so much that <command>cvs</command> can't
|
|
figure out how to apply the repository's changes). You'll have
|
|
to go through the file manually and resolve the conflicts;
|
|
they'll be marked with rows of <literal><</literal>,
|
|
<literal>=</literal> and <literal>></literal> signs. For
|
|
every conflict, there'll be a marker line with seven
|
|
<literal><</literal> signs and the name of the file,
|
|
followed by a chunk of what your local file contained,
|
|
followed by a separator line with seven <literal>=</literal>
|
|
signs, followed by the corresponding chunk in the
|
|
repository version, followed by a marker line with seven
|
|
<literal>></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's 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 -CURRENT and later
|
|
want to MFC it. The change you want to MFC was revision
|
|
1.15:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Check out the -STABLE version of the
|
|
<filename>shazam</filename> module:</para>
|
|
|
|
<screen>&prompt.user; <userinput>cvs co -rRELENG_4 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'll almost certainly get a conflict because
|
|
of the <literal>$Id: article.sgml,v 1.37 2000-09-24 07:01:47 kris Exp $</literal> (or in FreeBSD's case,
|
|
<literal>$FreeBSD<!-- stop expansion -->$</literal>) lines, so you'll have to edit
|
|
the file to resolve the conflict (remove the marker lines and
|
|
the second <literal>$Id: article.sgml,v 1.37 2000-09-24 07:01:47 kris Exp $</literal> line, leaving the original
|
|
<literal>$Id: article.sgml,v 1.37 2000-09-24 07:01:47 kris Exp $</literal> line intact).</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>View differences between the local version and the
|
|
repository version with the <literal>diff</literal>
|
|
command.</para>
|
|
|
|
<screen>&prompt.user; <userinput>cvs diff shazam</userinput></screen>
|
|
|
|
<para>shows you every modification you've made to the
|
|
<filename>shazam</filename> file or module.</para>
|
|
|
|
<para>Useful options:</para>
|
|
|
|
<informaltable>
|
|
<tgroup cols=2>
|
|
<tbody>
|
|
<row>
|
|
<entry><option>-u</option></entry>
|
|
<entry>Uses the unified diff format.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><option>-N</option></entry>
|
|
<entry>Shows missing or added files.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>You always want to use <option>-u</option>, since
|
|
unified diffs are much easier to read than almost any other
|
|
diff format (in some circumstances, context diffs may be
|
|
better, but they're much bulkier). A unified diff consists of
|
|
a series of hunks. Each hunk begins with a line that starts
|
|
with two <literal>@</literal> signs and specifies where in the
|
|
file the differences are and how many lines they span. This
|
|
is followed by a number of lines; some (preceded by a blank)
|
|
are context; some (preceded by a <literal>-</literal> sign)
|
|
are outtakes and some (preceded by a <literal>+</literal>) are
|
|
additions.</para>
|
|
|
|
<para>You can also diff against a different version
|
|
than the one you checked out by specifying a version
|
|
with <option>-r</option> or <option>-D</option> as in
|
|
<literal>checkout</literal> or <literal>update</literal>,
|
|
or even view the diffs between two arbitrary versions
|
|
(with no regard for what you have locally) by specifying
|
|
<emphasis>two</emphasis> versions with <option>-r</option> or
|
|
<option>-D</option>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>View log entries with the <literal>log</literal>
|
|
command.</para>
|
|
|
|
<!-- XXX needs more details -->
|
|
<screen>&prompt.user; <userinput>cvs log shazam</userinput></screen>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>See who did what with the <literal>annotate</literal> command.
|
|
This command shows you each line of the specified file or
|
|
files, along with which user most recently changed that
|
|
line.</para>
|
|
|
|
<screen>&prompt.user; <userinput>cvs annotate shazam</userinput></screen>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Add new files with the <literal>add</literal> command.</para>
|
|
|
|
<para>Create the file, <command>cvs add</command> it, then
|
|
<command>cvs commit</command> it.</para>
|
|
|
|
<para>Similarly, you can add new directories by creating them
|
|
and then <command>cvs add</command>ing them. Note that you
|
|
don't need to commit directories.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Remove obsolete files with the <literal>remove</literal> command.</para>
|
|
|
|
<para>Remove the file, then <command>cvs rm</command> it, then
|
|
<command>cvs commit</command> it.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Commit with the <literal>commit</literal> or
|
|
<literal>checkin</literal> command.</para>
|
|
|
|
<para>Useful options:</para>
|
|
|
|
<informaltable>
|
|
<tgroup cols=2>
|
|
<tbody>
|
|
<row>
|
|
<entry><option>-f</option></entry>
|
|
<entry>Force a commit of an unmodified file.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><option>-m<replaceable>msg</replaceable></option></entry>
|
|
<entry>Specify a commit message on the command line rather
|
|
than invoking an editor.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<para>Use the <option>-f</option> option if you realize that
|
|
you left out important information from the commit message.</para>
|
|
|
|
<para>Good commit messages are important. They tell others
|
|
why you did the changes you did, not just right here and now,
|
|
but months or years from now when someone wonders why some
|
|
seemingly illogical or inefficient piece of code snuck into
|
|
your source file. It's also an invaluable aid to deciding
|
|
which changes to MFC and which not to MFC.</para>
|
|
|
|
<para>Don't waste space in the commit messages explaining
|
|
<emphasis>what</emphasis> you did. That's what
|
|
<command>cvs diff</command> is for. Instead, tell us
|
|
<emphasis>why</emphasis> you did it.</para>
|
|
|
|
<para>Avoid committing several unrelated changes in one go. It
|
|
makes merging difficult, and also makes it harder to determine
|
|
which change is the culprit if a bug crops up.</para>
|
|
|
|
<para>Avoid committing style or whitespace fixes and
|
|
functionality fixes in one go. It makes merging difficult,
|
|
and also makes it harder to understand just what functional
|
|
changes were made.</para>
|
|
|
|
<para>Avoid committing changes to multiple files in one go
|
|
with a generic, vague message. Instead, commit each file (or
|
|
small groups of files) with tailored commit messages.</para>
|
|
|
|
<para>Before committing, <emphasis>always</emphasis>:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>verify which branch you're committing to, using
|
|
<command>cvs status</command>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>review your diffs, using
|
|
<command>cvs diff</command></para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Also, ALWAYS specify which files to commit explicitly on
|
|
the command line, so you don't accidentally commit other files
|
|
than the ones you intended - <command>cvs commit</command>
|
|
with no arguments will commit every modification in your
|
|
current working directory and every subdirectory.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>Additional tips and tricks:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
|
|
<para>You can place commonly used options in your
|
|
<filename>~/.cvsrc</filename>, like this:</para>
|
|
|
|
<programlisting>cvs -z3
|
|
diff -Nu
|
|
update -Pd
|
|
checkout -P</programlisting>
|
|
|
|
<para>This example says:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>always use compression level 3 when talking to a
|
|
remote server. This is a life-saver when working over a
|
|
slow connection.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>always use the <option>-N</option> (show added or
|
|
removed files) and <option>-u</option> (unified diff
|
|
format) options to &man.diff.1;.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>always use the <option>-P</option> (prune empty
|
|
directories) and <option>-d</option> (check out new
|
|
directories) options when updating.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>always use the <option>-P</option> (prune empty
|
|
directories) option when checking out.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Use Eivind Eklund's <command>cdiff</command> script to
|
|
view unidiffs. It's a wrapper for &man.less.1; that adds ANSI
|
|
color codes to make hunk headers, outtakes and additions stand
|
|
out; context and garbage are unmodified. It also expands tabs
|
|
properly (tabs often look wrong in diffs because of the extra
|
|
character in front of each line).</para>
|
|
|
|
<para><ulink url="http://people.freebsd.org/~eivind/cdiff">http://people.freebsd.org/~eivind/cdiff</ulink></para>
|
|
|
|
<para>Simply use instead of &man.more.1; or &man.less.1;:</para>
|
|
|
|
<screen>&prompt.user; <userinput>cvs diff -Nu shazam | cdiff</userinput></screen>
|
|
|
|
<para>Alternatively some editors like &man.vim.1;
|
|
(ports/editors/vim5) have color support and when used as
|
|
a pager with color syntax highlighting switched on will
|
|
highlight many types of file, including diffs, patches,
|
|
and cvs/rcs logs. </para>
|
|
|
|
<screen>&prompt.user; <userinput> echo "syn on" >> ~/.vimrc </userinput>
|
|
&prompt.user; <userinput> cvs diff -Nu shazam | vim -</userinput>
|
|
&prompt.user; <userinput> cvs log shazam | vim -</userinput> </screen>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>CVS is old, arcane, crufty and buggy, and sometimes
|
|
exhibits non-deterministic behavior which some claim as proof
|
|
that it's actually merely the newtonian manifestation of a
|
|
sentient transdimensional entity. It's not humanly possible
|
|
to know its every quirk inside out, so don't be afraid to ask
|
|
the resident AI (<email>cvs@FreeBSD.org</email>) for help when
|
|
you screw up.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="conventions">
|
|
<title>Conventions and Traditions</title>
|
|
|
|
<para>As a new committer there are a number of things you should do
|
|
first.</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Add yourself to the <quote>Developers</quote> section of the
|
|
Handbook and remove yourself from the <quote>Additional
|
|
Contributors</quote> section.</para>
|
|
|
|
<para>This is a relatively easy task, but remains a good first test of
|
|
your CVS skills.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Add an entry for yourself to
|
|
<filename>www/en/news/newsflash.sgml</filename>. Look for the other
|
|
entries that look like <quote>A new committer</quote> and follow the
|
|
format.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Some people also add an entry for themselves to
|
|
<filename>ports/astro/xearth/files/freebsd.committers.markers</filename>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Introduce yourself to the other committers, 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
|
|
committer in FreeBSD. Email this to
|
|
<email>cvs-committers@FreeBSD.org</email> 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 <email>cvs-committers@FreeBSD.org</email>. Really
|
|
large mailboxes which have taken up permanent residence on
|
|
<hostid>hub</hostid> often get <quote>accidently</quote> truncated
|
|
without warning, so forward it or read it and you will not lose
|
|
it.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>All new committers also have a mentor assigned to them for
|
|
the first few months. Your mentor is more or less responsible for
|
|
explaining anything which is confusing to you and is also
|
|
responsible for your actions during this initial period. If you
|
|
make a bogus commit, it is only going to embarrass your mentor
|
|
and you should probably make it a policy to pass at least your
|
|
first few commits by your mentor before committing it to the
|
|
repository.</para>
|
|
|
|
<para>All commits should go to <literal>-CURRENT</literal> first
|
|
before being merged to <literal>-STABLE</literal>. No major new
|
|
features or high-risk modifications should be made to the
|
|
<literal>-STABLE</literal> branch.</para>
|
|
</sect1>
|
|
|
|
<sect1 id="developer.relations">
|
|
<title>Developer Relations</title>
|
|
|
|
<para>If you are working directly on your own code or on code
|
|
which is already well established as your responsibility, then
|
|
there is probably little need to check with other committers
|
|
before jumping in with a commit. If you see a bug in an area of
|
|
the system which is clearly orphaned (and there are a few such
|
|
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
|
|
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>
|
|
to see who has committed changes in the past. &a.fenner; has
|
|
written a nice shell script that can help determine who the
|
|
active maintainer might be. It lists each person who has
|
|
committed to a given file along with the number of commits each
|
|
person has made. It can be found on <hostid>freefall</hostid>
|
|
at <filename>~fenner/bin/whodid</filename>. If your queries go
|
|
unanswered or the committer otherwise indicates a lack of
|
|
proprietary interest in the area affected, go ahead and commit
|
|
it.</para>
|
|
|
|
<para>If you are unsure about a commit for any reason at
|
|
all, have it reviewed by <literal>-hackers</literal>
|
|
before committing. Better to have it flamed then and there
|
|
rather than when it is part of the CVS repository. If you do
|
|
happen to commit something which results in controversy
|
|
erupting, you may also wish to consider backing the change out
|
|
again until the matter is settled. Remember – with CVS we
|
|
can always change it back.</para>
|
|
</sect1>
|
|
|
|
<sect1 id="gnats">
|
|
<title>GNATS</title>
|
|
|
|
<para>The FreeBSD Project utilizes
|
|
<application>GNATS</application> for tracking bugs and change
|
|
requests. Be sure that if you commit a fix or suggestion found
|
|
in a <application>GNATS</application> PR, you use
|
|
<command>edit-pr <replaceable>pr-number</replaceable></command>
|
|
on <hostid>freefall</hostid> to close it. It is also considered
|
|
nice if you take time to close any PRs associated with your
|
|
commits, if appropriate. Your can also make use of
|
|
&man.send-pr.1; yourself for proposing any change which you feel
|
|
should probably be made, pending a more extensive peer-review
|
|
first.</para>
|
|
|
|
<para>You can find out more about <application>GNATS</application>
|
|
at:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><ulink url="http://www.cs.utah.edu/csinfo/texinfo/gnats/gnats.html">http://www.cs.utah.edu/csinfo/texinfo/gnats/gnats.html</ulink></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><ulink url="http://www.FreeBSD.org/support.html">http://www.FreeBSD.org/support.html</ulink></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><ulink url="http://www.FreeBSD.org/send-pr.html">http://www.FreeBSD.org/send-pr.html</ulink></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>&man.send-pr.1;</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>You can run a local copy of GNATS, and then integrate the FreeBSD
|
|
GNATS tree in to it using CVSup. Then you can run GNATS commands
|
|
locally, or use other interfaces, such as <command>tkgnats</command>.
|
|
This lets you query the PR database without needing to be connected to
|
|
the Internet.</para>
|
|
|
|
<procedure>
|
|
<title>Using a local GNATS tree</title>
|
|
|
|
<step>
|
|
<para>If you are not already downloading the GNATS tree, add this line
|
|
to your <filename>supfile</filename>, and re-sup. Note that since
|
|
GNATS is not under CVS control it has no tag, so if you are adding
|
|
it to your existing <filename>supfile</filename> it should appear
|
|
before any <quote>tag=</quote> entry as these remain active once set.
|
|
</para>
|
|
|
|
<programlisting>gnats release=current prefix=/usr</programlisting>
|
|
|
|
<para>This will place the FreeBSD GNATS tree in
|
|
<filename>/usr/gnats</filename>. You can use a
|
|
<emphasis>refuse</emphasis> file to control which categories to
|
|
receive. For example, to only receive <literal>docs</literal> PRs,
|
|
put this line in
|
|
<filename>/usr/local/etc/cvsup/sup/refuse</filename><footnote>
|
|
<para>The precise path depends on the <literal>*default
|
|
base</literal> setting in your
|
|
<filename>supfile</filename>.</para>
|
|
</footnote>.</para>
|
|
|
|
<programlisting>gnats/[a-ce-z]*</programlisting>
|
|
|
|
<para>The rest of these examples assume you have only supped the
|
|
<literal>docs</literal> category. Adjust them as necessary,
|
|
depending on the categories you are synching.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Install the GNATS port from
|
|
<filename>ports/databases/gnats</filename>. This will place the
|
|
various GNATS directories under
|
|
<filename>$PREFIX/share/gnats</filename>.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Symlink the GNATS directories you are supping under the version
|
|
of GNATS you have installed.</para>
|
|
|
|
<screen>&prompt.root; <userinput>cd /usr/local/share/gnats/gnats-db</userinput>
|
|
&prompt.root; <userinput>ln -s /usr/gnats/docs</userinput></screen>
|
|
|
|
<para>Repeat as necessary, depending on how many GNATS categories you
|
|
are synching.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Update the GNATS <filename>categories</filename> file with these
|
|
cageories. The file is
|
|
<filename>$PREFIX/share/gnats/gnats-db/gnats-adm/categories</filename>.</para>
|
|
|
|
<programlisting># This category is mandatory
|
|
pending:Category for faulty PRs:gnats-admin:
|
|
#
|
|
# FreeBSD categories
|
|
#
|
|
docs:Documentation Bug:nik:</programlisting>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Run <filename>$PREFIX/libexec/gnats/gen-index</filename> to
|
|
recreate the GNATS index. The output has to be redirected to
|
|
<filename>$PREFIX/share/gnats/gnats-db/gnats-adm/index</filename>.
|
|
You can do this periodically from &man.cron.8;, or run &man.cvsup.1;
|
|
from a shell script that does this as well.</para>
|
|
|
|
<screen>&prompt.root; <userinput>/usr/local/libexec/gnats/gen-index \
|
|
> /usr/local/share/gnats/gnats-db/gnats-adm/index</userinput></screen>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Test the configuration by querying the PR database. This
|
|
command shows open <literal>docs</literal> PRs.</para>
|
|
|
|
<screen>&prompt.root; <userinput>query-pr -c docs -s open</userinput></screen>
|
|
|
|
<para>Other interfaces, like
|
|
<filename>ports/databases/tkgnats</filename> should also work
|
|
nicely.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Pick a PR and close it.</para>
|
|
</step>
|
|
</procedure>
|
|
|
|
<note>
|
|
<para>This procedure only works to allow you to view and query the PRs
|
|
locally. To edit or close them you will still have to log in to
|
|
<hostid>freefall</hostid> and do it from there.</para>
|
|
</note>
|
|
</sect1>
|
|
|
|
<sect1 id="people">
|
|
<title>Who's Who</title>
|
|
|
|
<para>Besides Peter Wemm and John Polstra, the repository
|
|
meisters, there are other FreeBSD project members whom you will
|
|
probably get to know in your role as a committer. Briefly,
|
|
and by no means all-inclusively, these are:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>&a.asami;</term>
|
|
|
|
<listitem>
|
|
<para>Satoshi is the Ports Wraith, meaning that he has
|
|
ultimate authority over any modifications to the ports
|
|
collection or the ports skeleton makefiles. He is also
|
|
the one responsible for administering ports freezes before
|
|
the releases.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>&a.bde;</term>
|
|
|
|
<listitem>
|
|
<para>Bruce is the Obersturmbahnfuhrer of the Style Police.
|
|
When you do a commit that could have been done better,
|
|
Bruce will be there to tell you. Be thankful that someone
|
|
is.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>&a.dg;</term>
|
|
|
|
<listitem>
|
|
<para>David is our principal architect and overseer of the
|
|
VM system. If you have a VM system change in mind,
|
|
coordinate it with David. Should you become locked in a
|
|
bitter, intractable dispute with some other committer over
|
|
a proposed change (which does not happen very often,
|
|
thankfully) then an appeal to David to put on his P.A. hat
|
|
and make a final decision might be necessary.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>&a.jkh;</term>
|
|
|
|
<listitem>
|
|
<para>Jordan is the release engineer. He is responsible for
|
|
setting release deadlines and controlling the release
|
|
process. During code freezes, he also has final authority
|
|
on all changes to the system for whichever branch is
|
|
pending release status. If there is something you want
|
|
merged from <literal>-CURRENT</literal> to
|
|
<literal>-STABLE</literal> (whatever values those may have
|
|
at any given time), he is also the one to talk to about
|
|
it.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>&a.steve;</term>
|
|
|
|
<listitem>
|
|
<para>Steve is the unofficial maintainer of
|
|
<filename>src/bin</filename>. If you have something
|
|
significant you'd like to do there, you should probably
|
|
coordinate it with Steve first. He is also a Problem
|
|
Report-meister, along with &a.phk;.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>&a.brian;</term>
|
|
|
|
<listitem>
|
|
<para>Official maintainer of
|
|
<filename>/usr/bin/ppp</filename> and LPD.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>&a.wollman;</term>
|
|
|
|
<listitem>
|
|
<para>If you need advice on obscure network internals or
|
|
aren't sure of some potential change to the networking
|
|
subsystem you have in mind, Garrett is someone to talk
|
|
to.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</sect1>
|
|
|
|
<sect1 id="ssh.guide">
|
|
<title>SSH Quick-Start Guide</title>
|
|
|
|
<procedure>
|
|
<step>
|
|
<para>If you are using FreeBSD 4.0 or later,
|
|
OpenSSH is included in the base system.
|
|
If you are using an earlier release,
|
|
update and install one of the SSH ports. In general,
|
|
you will probably want to get OpenSSH from the port in
|
|
<filename>/usr/ports/security/openssh</filename>. You
|
|
may also wish to check out the original ssh1 in
|
|
<filename>/usr/ports/security/ssh</filename>, but make
|
|
certain you pay attention to its license. Note that both
|
|
of these ports cannot be installed at the same time.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>If you do not wish to to type your password in every
|
|
time you use &man.ssh.1;, and you use RSA keys to
|
|
authenticate, &man.ssh-agent.1; is there for your
|
|
convenience. If you want to use &man.ssh-agent.1;, make
|
|
sure that you run it before running other applications. X
|
|
users, for example, usually do this from their
|
|
<filename>.xsession</filename> or
|
|
<filename>.xinitrc</filename> file. See &man.ssh-agent.1;
|
|
for details.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Generate a key pair using &man.ssh-keygen.1;. The key
|
|
pair will wind up in the
|
|
<filename><envar>$HOME</envar>/.ssh</filename>
|
|
directory.</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Send your public key
|
|
(<filename><envar>$HOME</envar>/.ssh/identity.pub</filename>)
|
|
to the person setting you up as a committer so it can be put
|
|
into your <filename>authorized_keys</filename> file in your
|
|
home directory on <hostid>freefall</hostid>
|
|
(i.e.
|
|
<filename><envar>$HOME</envar>/.ssh/authorized_keys</filename>).
|
|
</para>
|
|
</step>
|
|
</procedure>
|
|
|
|
<para>Now you should be able to use &man.ssh-add.1; for
|
|
authentication once per session. This will prompt you for
|
|
your private key's pass phrase, and then store it in your
|
|
authentication agent (&man.ssh-agent.1;). If you no longer
|
|
wish to have your key stored in the agent, issuing
|
|
<command>ssh-add -d</command> will remove it.</para>
|
|
|
|
<para>Test by doing something such as <command>ssh
|
|
freefall.FreeBSD.org ls /usr</command>.</para>
|
|
|
|
<para>For more information, see
|
|
<filename>/usr/ports/security/openssh</filename>, &man.ssh.1;,
|
|
&man.ssh-add.1;, &man.ssh-agent.1;, &man.ssh-keygen.1;, and
|
|
&man.scp.1;.</para>
|
|
</sect1>
|
|
|
|
<sect1>
|
|
<title>The FreeBSD Committers' Big List of Rules</title>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Respect other committers.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Discuss any significant change
|
|
<emphasis>before</emphasis> committing.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Respect existing maintainers if listed in the
|
|
(<makevar>MAINTAINER</makevar> field in
|
|
<filename>Makefile</filename> or in the
|
|
<filename>MAINTAINER</filename> file in the top-level
|
|
directory).</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Never touch the repository directly. Ask a
|
|
Repomeister.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Any disputed change must be backed out pending
|
|
resolution of the dispute if requested by a maintainer or
|
|
the Principal Architect. Security related changes may
|
|
override a maintainer's wishes at the Security Officer's
|
|
discretion.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Changes go to <literal>-CURRENT</literal> before
|
|
<literal>-STABLE</literal> unless specifically permitted by
|
|
the release engineer or unless they're not applicable to
|
|
<literal>-CURRENT</literal>. Any non-trivial or non-urgent
|
|
change which is applicable should also be allowed to sit in
|
|
<literal>-CURRENT</literal> for at least 3 days before
|
|
merging so that it can be given sufficient testing. The
|
|
release engineer has the same authority over the
|
|
<literal>-STABLE</literal> branch as outlined for the
|
|
Principal Architect in rule #5.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Don't fight in public with other committers; it looks
|
|
bad. If you must <quote>strongly disagree</quote> about
|
|
something, do so only in private.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Respect all code freezes and read the
|
|
<literal>committers</literal> mailing list on a timely basis
|
|
so you know when a code freeze is in effect.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>When in doubt on any procedure, ask first!</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Test your changes before committing them.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>As noted, breaking some of these rules can be grounds for
|
|
suspension or, upon repeated offense, permanent removal of
|
|
commit privileges. Three or more members of core, or the
|
|
Principal Architect and another member of core acting in unison,
|
|
have the power to temporarily suspend commit privileges until
|
|
<literal>-core</literal> as a whole has the chance to review the
|
|
issue. In case of an <quote>emergency</quote> (a committer
|
|
doing damage to the repository), a temporary suspension may also
|
|
be done by the repository meisters or any other member of core
|
|
who may happen to be awake at the time. Only core as a whole
|
|
has the authority to suspend commit privileges for any
|
|
significant length of time or to remove them permanently, the
|
|
latter generally only being done after consultation with
|
|
committers. This rule does not exist to set core up as a bunch
|
|
of cruel dictators who can dispose of committers as casually as
|
|
empty soda cans, but to give the project a kind of safety fuse.
|
|
If someone is seriously out of control, it's important to be
|
|
able to deal with this immediately rather than be paralyzed by
|
|
debate. In all cases, a committer whose privileges are
|
|
suspended or revoked is entitled to a <quote>hearing</quote>,
|
|
the total duration of the suspension being determined at that
|
|
time. A committer whose privileges are suspended may also
|
|
request a review of the decision after 30 days and every 30 days
|
|
thereafter (unless the total suspension period is less than 30
|
|
days). A committer whose privileges have been revoked entirely
|
|
may request a review after a period of 6 months have elapsed.
|
|
This review policy is <emphasis>strictly informal</emphasis>
|
|
and, in all cases, core reserves the right to either act on or
|
|
disregard requests for review if they feel their original
|
|
decision to be the right one.</para>
|
|
|
|
<para>In all other aspects of project operation, core is a subset
|
|
of committers and is bound by the <emphasis>same
|
|
rules</emphasis>. Just because someone is in core doesn't mean
|
|
that they have special dispensation to step outside of any of
|
|
the lines painted here; core's <quote>special powers</quote>
|
|
only kick in when it acts as a group, not on an individual
|
|
basis. As individuals, we are all committers first and core
|
|
second.</para>
|
|
|
|
<sect2>
|
|
<title>Details</title>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Respect other committers.</para>
|
|
|
|
<para>This means that you need to treat other committers as
|
|
the peer-group developers that they are. Despite our
|
|
occasional attempts to prove the contrary, one doesn't get
|
|
into committers by being stupid and nothing rankles more
|
|
than being treated that way by one of your peers. Whether
|
|
we always feel respect for one another or not (and
|
|
everyone has off days), we still have to
|
|
<emphasis>treat</emphasis> other committers with respect
|
|
at all times or the whole team structure rapidly breaks
|
|
down.</para>
|
|
|
|
<para>Being able to work together long term is this project's
|
|
greatest asset, one far more important than any set of
|
|
changes to the code, and turning arguments about code into
|
|
issues that affect our long-term ability to work
|
|
harmoniously together is just not worth the trade-off by
|
|
any conceivable stretch of the imagination.</para>
|
|
|
|
<para>To comply with this rule, don't send email when you're
|
|
angry or otherwise behave in a manner which is likely to
|
|
strike others as needlessly confrontational. First calm
|
|
down, then think about how to communicate in the most
|
|
effective fashion for convincing the other person(s) that
|
|
your side of the argument is correct, don't just blow off
|
|
some steam so you can feel better in the short term at the
|
|
cost of a long-term flame war. Not only is this very bad
|
|
<quote>energy economics</quote>, but repeated displays of
|
|
public aggression which impair our ability to work well
|
|
together will be dealt with severely by the project
|
|
leadership and may result in suspension or termination of
|
|
your commit privileges. That's never an option which the
|
|
project's leadership enjoys in the slightest, but unity
|
|
comes first. No amount of code or good advice is worth
|
|
trading that away.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Discuss any significant change
|
|
<emphasis>before</emphasis> committing.</para>
|
|
|
|
<para>The CVS repository is not where changes should be
|
|
initially submitted for correctness or argued over, that
|
|
should happen first in the mailing lists and then
|
|
committed only once something resembling consensus has
|
|
been reached. This doesn't mean that you have to ask
|
|
permission before correcting every obvious syntax error or
|
|
man page misspelling, simply that you should try to
|
|
develop a feel for when a proposed change isn't quite such
|
|
a no-brainer and requires some feedback first. People
|
|
really don't mind sweeping changes if the result is
|
|
something clearly better than what they had before, they
|
|
just don't like being <emphasis>surprised</emphasis> by
|
|
those changes. The very best way of making sure that
|
|
you're on the right track is to have your code reviewed by
|
|
one or more other committers.</para>
|
|
|
|
<para>When in doubt, ask for review!</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Respect existing maintainers if listed.</para>
|
|
|
|
<para>Many parts of FreeBSD aren't <quote>owned</quote> in
|
|
the sense that any specific individual will jump up and
|
|
yell if you commit a change to <quote>their</quote> area,
|
|
but it still pays to check first. One convention we use
|
|
is to put a maintainer line in the
|
|
<filename>Makefile</filename> for any package or subtree
|
|
which is being actively maintained by one or more people;
|
|
see <ulink
|
|
url="http://www.FreeBSD.org/handbook/policies.html">http://www.FreeBSD.org/handbook/policies.html</ulink>
|
|
for documentation on this. Where sections of code have
|
|
several maintainers, commits to affected areas by one
|
|
maintainer need to be reviewed by at least one other
|
|
maintainer. In cases where the
|
|
<quote>maintainer-ship</quote> of something isn't clear,
|
|
you can also look at the CVS logs for the file(s) in
|
|
question and see if someone has been working recently or
|
|
predominantly in that area.</para>
|
|
|
|
<para>Other areas of FreeBSD fall under the control of
|
|
someone who manages an overall category of FreeBSD
|
|
evolution, such as internationalization or networking.
|
|
See <ulink url="http://www.FreeBSD.org/handbook/staff-who.html">http://www.FreeBSD.org/handbook/staff-who.html</ulink>
|
|
for more information on this.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Never touch the repository directly. Ask a
|
|
Repomeister.</para>
|
|
|
|
<para>This is pretty clear - you're not allowed to make
|
|
direct modifications to the CVS repository, period. In
|
|
case of difficulty, ask one of the repository meisters by
|
|
sending mail to <email>cvs@FreeBSD.org</email> and simply
|
|
wait for them to fix the problem and get back to you. Do
|
|
not attempt to fix the problem yourself!</para>
|
|
|
|
<para>If you're thinking about putting down a tag or doing a
|
|
new import of code on a vendor branch, you might also find
|
|
it useful to ask for advice first. A lot of people get
|
|
this wrong the first few times and the consequences are
|
|
expensive in terms of files touched and angry CVSup/CTM
|
|
folks who are suddenly getting a lot of changes sent over
|
|
unnecessarily.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Any disputed change must be backed out pending
|
|
resolution of the dispute if requested by a maintainer or
|
|
the Principal Architect. Security related changes may
|
|
override a maintainer's wishes at the Security Officer's
|
|
discretion.</para>
|
|
|
|
<para>This may be hard to swallow in times of conflict (when
|
|
each side is convinced that they're in the right, of
|
|
course) but CVS makes it unnecessary to have an ongoing
|
|
dispute raging when it's far easier to simply reverse the
|
|
disputed change, get everyone calmed down again and then
|
|
try and figure out how best to proceed. If the change
|
|
turns out to be the best thing after all, it can be easily
|
|
brought back. If it turns out not to be, then the users
|
|
didn't have to live with the bogus change in the tree
|
|
while everyone was busily debating its merits. People
|
|
very very rarely call for back-outs in the repository
|
|
since discussion generally exposes bad or controversial
|
|
changes before the commit even happens, but on such rare
|
|
occasions the back-out should be done without argument so
|
|
that we can get immediately on to the topic of figuring
|
|
out whether it was bogus or not.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Changes go to <literal>-CURRENT</literal> before
|
|
<literal>-STABLE</literal> unless specifically permitted
|
|
by the release engineer or unless they're not applicable
|
|
to <literal>-CURRENT</literal>. Any non-trivial or
|
|
non-urgent change which is applicable should also be
|
|
allowed to sit in <literal>-CURRENT</literal> for at least
|
|
3 days before merging so that it can be given sufficient
|
|
testing. The release engineer has the same authority over
|
|
the <literal>-STABLE</literal> branch as outlined in rule
|
|
#5.</para>
|
|
|
|
<para>This is another <quote>don't argue about it</quote>
|
|
issue since it's the release engineer who is ultimately
|
|
responsible (and gets beaten up) if a change turns out to
|
|
be bad. Please respect this and give the release engineer
|
|
your full cooperation when it comes to the
|
|
<literal>-STABLE</literal> branch. The management of
|
|
<literal>-STABLE</literal> may frequently seem to be
|
|
overly conservative to the casual observer, but also bear
|
|
in mind the fact that conservatism is supposed to be the
|
|
hallmark of <literal>-STABLE</literal> and different rules
|
|
apply there than in <literal>-CURRENT</literal>. There's
|
|
also really no point in having <literal>-CURRENT</literal>
|
|
be a testing ground if changes are merged over to
|
|
<literal>-STABLE</literal> immediately. Changes need a
|
|
chance to be tested by the <literal>-CURRENT</literal>
|
|
developers, so allow some time to elapse before merging
|
|
unless the <literal>-STABLE</literal> fix is critical,
|
|
time sensitive or so obvious as to make further testing
|
|
unnecessary (spelling fixes to manpages, obvious bug/typo
|
|
fixes, etc.) In other words, apply common sense.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Don't fight in public with other committers; it looks
|
|
bad. If you must <quote>strongly disagree</quote> about
|
|
something, do so only in private.</para>
|
|
|
|
<para>This project has a public image to uphold and that
|
|
image is very important to all of us, especially if we are
|
|
to continue to attract new members. There will be
|
|
occasions when, despite everyone's very best attempts at
|
|
self-control, tempers are lost and angry words are
|
|
exchanged, and the best we can do is try and minimize the
|
|
effects of this until everyone has cooled back down. That
|
|
means that you should not air your angry words in public
|
|
and you should not forward private correspondence to
|
|
public mailing lists or aliases. What people say
|
|
one-to-one is often much less sugar-coated than what they
|
|
would say in public, and such communications therefore
|
|
have no place there - they only serve to inflame an
|
|
already bad situation. If the person sending you a
|
|
flame-o-gram at least had the grace to send it privately,
|
|
then have the grace to keep it private yourself. If you
|
|
feel you are being unfairly treated by another developer,
|
|
and it is causing you anguish, bring the matter up with
|
|
core rather than taking it public. We will do our best to
|
|
play peace makers and get things back to sanity. In cases
|
|
where the dispute involves a change to the codebase and
|
|
the participants do not appear to be reaching an amicable
|
|
agreement, core may appoint a mutually-agreeable 3rd party
|
|
to resolve the dispute. All parties involved must then
|
|
agree to be bound by the decision reached by this 3rd
|
|
party.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Respect all code freezes and read the
|
|
<literal>committers</literal> mailing list on a timely
|
|
basis so you know when they are.</para>
|
|
|
|
<para>Committing changes during a code freeze is a really
|
|
big mistake and committers are expected to keep up-to-date
|
|
on what's going on before jumping in after a long absence
|
|
and committing 10 megabytes worth of accumulated stuff.
|
|
People who abuse this on a regular basis will have their
|
|
commit privileges suspended until they get back from the
|
|
FreeBSD Happy Reeducation Camp we run in Greenland.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>When in doubt on any procedure, ask first!</para>
|
|
|
|
<para>Many mistakes are made because someone is in a hurry
|
|
and just assumes they know the right way of doing
|
|
something. If you have not done it before, chances are
|
|
good that you do not actually know the way we do things
|
|
and really need to ask first or you are going to
|
|
completely embarrass yourself in public. There's no shame
|
|
in asking <quote>how in the heck do I do this?</quote> We
|
|
already know you are an intelligent person; otherwise, you
|
|
would not be a committer.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Test your changes before committing them.</para>
|
|
|
|
<para>This may sound obvious, but if it really were so
|
|
obvious then we probably wouldn't see so many cases of
|
|
people clearly not doing this. If your changes are to the
|
|
kernel, make sure you can still compile both GENERIC and
|
|
LINT. If your changes are anywhere else, make sure you
|
|
can still make world. If your changes are to a branch,
|
|
make sure your testing occurs with a machine which is
|
|
running that code. If you have a change which also may
|
|
break another architecture, be sure and test on all
|
|
supported architectures. Currently, this is only the x86
|
|
and the alpha so it's pretty easy to do. If you need to
|
|
test on the AXP, your account on <hostid
|
|
role="fqdn">beast.FreeBSD.org</hostid> will let you
|
|
compile and test alpha binaries/kernels/etc. As other
|
|
architectures are added to the FreeBSD supported platforms
|
|
list, the appropriate shared testing resources will be
|
|
made available.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Other Suggestions</title>
|
|
|
|
<para>When committing documentation changes, use a spell checker
|
|
before committing. :) For all SGML docs, you should also
|
|
verify that your formatting directives are correct by running
|
|
<command>make lint</command>.</para>
|
|
|
|
<para>For all on-line manual pages, run <command>manck</command>
|
|
(from ports) over the man page to verify the all of the cross
|
|
references and file references are correct and that the man
|
|
page has all of the appropriate <makevar>MLINK</makevar>s
|
|
installed.</para>
|
|
|
|
<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
|
|
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
|
|
makes the translators' job much more difficult. Instead, make
|
|
any style or whitespace changes in seperate commits that are
|
|
clearly labeled as such in the commit message.</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1>
|
|
<title>Ports Specific FAQ</title>
|
|
|
|
<qandaset>
|
|
<qandadiv>
|
|
<title>Importing a New Port</title>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>How do I import a new port?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>First, please read the section about repository
|
|
copy.</para>
|
|
|
|
<para>The easiest way to import a new port is to use the
|
|
<command>addport</command> script on
|
|
<hostid>freefall</hostid>. It will import a port from the
|
|
directory you specify, determining the category automatically
|
|
from the port <filename>Makefile</filename>.
|
|
It will also add an entry to the
|
|
<filename>CVSROOT/modules</filename> file and the port's
|
|
category <filename>Makefile</filename>. It was
|
|
written by &a.mharo; and &a.will;, but Will is the current
|
|
maintainer so please send questions/patches about
|
|
<command>addport</command> to him.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>Any other things I need to know when I import a new
|
|
port?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>Check the port, preferably to make sure it compiles
|
|
and packages correctly. This is the recommended
|
|
sequence:</para>
|
|
|
|
<screen>&prompt.root; <userinput>make install</userinput>
|
|
&prompt.root; <userinput>make package</userinput>
|
|
&prompt.root; <userinput>make deinstall</userinput>
|
|
&prompt.root; <userinput>pkg_add <replaceable>package you built above</replaceable></userinput>
|
|
&prompt.root; <userinput>make deinstall</userinput>
|
|
&prompt.root; <userinput>make reinstall</userinput>
|
|
&prompt.root; <userinput>make package</userinput>
|
|
</screen>
|
|
|
|
<para>The
|
|
<ulink url="http://www.freebsd.org/porters-handbook/index.html">Porters
|
|
Handbook</ulink> contains more detailed
|
|
instructions.</para>
|
|
|
|
<para>Use &man.portlint.1; to check the syntax of the port.
|
|
You don't necessarily have to eliminate all warnings but
|
|
make sure you have fixed the simple ones.</para>
|
|
|
|
<para>If the port came from a submitter who has not
|
|
contributed to the project before, add that person's
|
|
name to the Handbook's <citetitle
|
|
pubwork="section">Additional Contributors</citetitle>
|
|
section.</para>
|
|
|
|
<para>Close the PR if the port came in as a PR. To close
|
|
a PR, just do
|
|
<userinput>edit-pr <replaceable>PR#</replaceable></userinput>
|
|
on <hostid>freefall</hostid> and change the
|
|
<varname>state</varname> from <constant>open</constant>
|
|
to <constant>closed</constant>. You will be asked to
|
|
enter a log message and then you are done.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
</qandadiv>
|
|
|
|
<qandadiv>
|
|
<title>Repository Copies</title>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>When do we need a repository copy?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>When you want to import a port that is related to
|
|
any port that is already in the tree in a separate
|
|
directory, please send mail to the ports manager asking
|
|
about it. Here <wordasword>related</wordasword> means
|
|
it is a different version or a slightly modified
|
|
version. Examples are
|
|
<filename>print/ghostscript*</filename> (different
|
|
versions) and <filename>x11-wm/windowmaker*</filename>
|
|
(English-only and internationalized version).</para>
|
|
|
|
<para>Another example is when a port is moved from one
|
|
subdirectory to another, or when you want to change the
|
|
name of a directory because the author(s) renamed their
|
|
software even though it is a
|
|
descendant of a port already in a tree.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>When do we <emphasis>not</emphasis> need a
|
|
repository copy?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>When there is no history to preserve. If a port is
|
|
imported into a wrong category and is moved immediately,
|
|
it suffices to simply <command>cvs remove</command> the
|
|
old one and <command>cvs import</command> the new
|
|
one.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>What do I need to do?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>Send mail to the ports manager, who will do a copy
|
|
from the old location/name to the new location/name.
|
|
You will then get a notice, at which point you are
|
|
expected to perform the following:</para>
|
|
|
|
<procedure>
|
|
<step>
|
|
<para><command>cvs remove</command> the old port (if
|
|
necessary)</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Adjust the parent (category)
|
|
<filename>Makefile</filename></para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>Update <filename>CVSROOT/modules</filename></para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>If other ports depend on the updated port,
|
|
change their <filename>Makefile</filename>s'
|
|
dependency lines</para>
|
|
</step>
|
|
|
|
<step>
|
|
<para>If the port changed categories, modify the
|
|
<makevar>CATEGORIES</makevar> line of the port's
|
|
<filename>Makefile</filename> accordingly</para>
|
|
</step>
|
|
</procedure>
|
|
</answer>
|
|
</qandaentry>
|
|
</qandadiv>
|
|
|
|
<qandadiv>
|
|
<title>Ports Freeze</title>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>What is a <quote>ports freeze</quote>?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>Before a release, it is necessary to restrict
|
|
commits to the ports tree for a short period of time
|
|
while the packages and the release itself are being
|
|
built. This is to ensure consistency among the various
|
|
parts of the release, and is called the <quote>ports
|
|
freeze</quote>.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>How long is a ports freeze?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>Usually two to three days.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>What does it mean to me?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>During the ports freeze, you are not allowed to
|
|
commit anything to the tree without explicit approval
|
|
from the ports manager. <quote>Explicit
|
|
approval</quote> here means either of the
|
|
following:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>You asked the ports manager and got a reply
|
|
saying, <quote>Go ahead and commit
|
|
it.</quote></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The ports manager sent a mail to you or the
|
|
mailing lists during the ports freeze pointing out
|
|
that the port is broken and has to be fixed.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Note that you do not have implicit permission to fix
|
|
a port during the freeze just because it is
|
|
broken.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>How do I know when the ports freeze starts?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>The ports manager will send out warning messages to
|
|
the <email>freebsd-ports@FreeBSD.org</email> and
|
|
<email>cvs-committers@FreeBSD.org</email> mailing lists
|
|
announcing the start of the impending release, usually
|
|
two or three weeks in advance. The exact starting time
|
|
will not be determined until a few days before the
|
|
actual release. This is because the ports freeze has to
|
|
be synchronized with the release, and it is usually not
|
|
known until then when exactly the release will be
|
|
rolled.</para>
|
|
|
|
<para>When the freeze starts, there will be another
|
|
announcement to the
|
|
<email>cvs-committers@FreeBSD.org</email> list, of
|
|
course.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>How do I know when the ports freeze ends?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>A few hours after the release, the ports manager
|
|
will send out a mail to the
|
|
<email>freebsd-ports@FreeBSD.org</email> and
|
|
<email>cvs-committers@FreeBSD.org</email> mailing lists
|
|
announcing the end of the ports freeze. Note that the
|
|
release being cut does not automatically end the freeze.
|
|
We have to make sure there will not be any last minute
|
|
snafus that result in an immediate re-rolling of the
|
|
release.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
</qandadiv>
|
|
|
|
<qandadiv>
|
|
<title>Miscellaneous Questions</title>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>How do I know if my port is building correctly or
|
|
not?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>First, go check
|
|
<ulink url="http://bento.FreeBSD.org/~asami/errorlogs/">http://bento.FreeBSD.org/~asami/errorlogs/</ulink>.
|
|
|
|
There you will find error logs from the latest package
|
|
building runs on 3-stable and 4-current.</para>
|
|
|
|
<para>However, just because the port doesn't show up there
|
|
doesn't mean it's building correctly. (One of the
|
|
dependencies may have failed, for instance.) Here are
|
|
the relevant directories on bento, so feel free to dig
|
|
around.</para>
|
|
|
|
<programlisting> /a/asami/portbuild/3/errors error logs from latest 3-stable run
|
|
/logs all logs from latest 3-stable run
|
|
/packages packages from latest 3-stable run
|
|
/bak/errors error logs from last complete 3-stable run
|
|
/bak/logs all logs from last complete 3-stable run
|
|
/bak/packages packages from last complete 3-stable run
|
|
/4/errors error logs from latest 4-current run
|
|
/logs all logs from latest 4-current run
|
|
/packages packages from latest 4-current run
|
|
/bak/errors error logs from last complete 4-current run
|
|
/bak/logs all logs from last complete 4-current run
|
|
/bak/packages packages from last complete 4-current run
|
|
</programlisting>
|
|
|
|
<para>Basically, if the port shows up in
|
|
<filename>packages</filename>, or it is in
|
|
<filename>logs</filename> but not in
|
|
<filename>errors</filename>, it built fine. (The
|
|
<filename>errors</filename> directories are what you get
|
|
from the web page.)</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>I added a new port. Do I need to add it to the
|
|
<filename>INDEX</filename>?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>No. The ports manager will regenerate the
|
|
<filename>INDEX</filename> and commit it every few
|
|
days.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>Are there any other files I'm not allowed to
|
|
touch?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>Any file directly under <filename>ports/</filename>, or
|
|
any file under a subdirectory that starts with an
|
|
uppercase letter (<filename>Mk/</filename>,
|
|
<filename>Tools/</filename>, etc.). In particular, the
|
|
ports manager is very protective of
|
|
<filename>ports/Mk/bsd.port*.mk</filename> so don't
|
|
commit changes to those files unless you want to face his
|
|
wra(i)th.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
</qandadiv>
|
|
</qandaset>
|
|
</sect1>
|
|
|
|
<sect1>
|
|
<title>Miscellaneous Questions</title>
|
|
|
|
<qandaset>
|
|
<qandaentry>
|
|
<question>
|
|
<para>Why are trivial or cosmetic changes to files on a vendor
|
|
branch a bad idea?</para>
|
|
</question>
|
|
|
|
<answer>
|
|
<para>The RCS file format is quite braindead and certain
|
|
operations to achieve things for CVS are hideously
|
|
expensive for the repository. Making changes to files on
|
|
a vendor branch, thereby pulling the file off that branch,
|
|
is one example of this.</para>
|
|
|
|
<para>Suppose you have a file which was first imported on a
|
|
vendor branch, and was then re-imported three times (still
|
|
on the vendor branch) as the vendor makes updates to the
|
|
file.</para>
|
|
|
|
<segmentedlist>
|
|
<seglistitem>
|
|
<seg>1.1.1.1</seg>
|
|
<seg>vendor import</seg>
|
|
</seglistitem>
|
|
|
|
<seglistitem>
|
|
<seg>1.1.1.2</seg>
|
|
<seg>vendor import, +1000, -500 lines</seg>
|
|
</seglistitem>
|
|
|
|
<seglistitem>
|
|
<seg>1.1.1.3</seg>
|
|
<seg>vendor import, +2000, -500 lines</seg>
|
|
</seglistitem>
|
|
|
|
<seglistitem>
|
|
<seg>1.1.1.4</seg>
|
|
<seg>vendor import, +1000, -1000 lines</seg>
|
|
</seglistitem>
|
|
</segmentedlist>
|
|
|
|
<para>Now suppose that one of the FreeBSD committers makes a
|
|
one line change to this file, causing it to go to version
|
|
1.2. This causes it to leave the branch, resulting in
|
|
4,001 lines being added to the file's history, and 2,001
|
|
lines being deleted.</para>
|
|
|
|
<para>This is because the 1.2 delta is stored relative to
|
|
1.1.1.1, <emphasis>not</emphasis> 1.1.1.4, and so the
|
|
entire vendor history is duplicated in the 1.2 delta.
|
|
Now, repeat this for 2000 files in a large directory, it
|
|
adds up a lot.</para>
|
|
|
|
<para><emphasis>This</emphasis> is why we have such
|
|
<quote>hands off</quote> policies for
|
|
<filename>src/contrib</filename> and other things that
|
|
track the vendor releases. This is why <quote>typo
|
|
fixes</quote> in man pages and spelling
|
|
<quote>corrections</quote> are so strongly discouraged for
|
|
vendor code.</para>
|
|
</answer>
|
|
</qandaentry>
|
|
|
|
<qandaentry>
|
|
<question>
|
|
<para>How do I add a new file to a CVS 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_4 and it does not exist in RELENG_4 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_4</userinput>
|
|
cvs update: Updating .
|
|
U clockvar.h
|
|
U console.h
|
|
...
|
|
&prompt.user; <userinput>cvs update -kk -Ap smp.h > 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_4'
|
|
cvs add: use 'cvs commit' to add this file permanently
|
|
&prompt.user; <userinput>cvs commit</userinput>
|
|
</screen>
|
|
</example>
|
|
</answer>
|
|
</qandaentry>
|
|
</qandaset>
|
|
</sect1>
|
|
</article>
|