diff options
Diffstat (limited to 'en_US.ISO8859-1/articles/committers-guide')
| -rw-r--r-- | en_US.ISO8859-1/articles/committers-guide/Makefile | 27 | ||||
| -rw-r--r-- | en_US.ISO8859-1/articles/committers-guide/article.sgml | 2252 |
2 files changed, 0 insertions, 2279 deletions
diff --git a/en_US.ISO8859-1/articles/committers-guide/Makefile b/en_US.ISO8859-1/articles/committers-guide/Makefile deleted file mode 100644 index 51fe6d2820..0000000000 --- a/en_US.ISO8859-1/articles/committers-guide/Makefile +++ /dev/null @@ -1,27 +0,0 @@ -# -# $FreeBSD: doc/en_US.ISO_8859-1/articles/committers-guide/Makefile,v 1.3 1999/09/06 06:52:35 peter Exp $ -# -# Build the FreeBSD New Committers Guide -# - -MAINTAINER=jhb@FreeBSD.org - -DOC?= article - -FORMATS?= html - -INSTALL_COMPRESSED?= gz -INSTALL_ONLY_COMPRESSED?= - -JADEFLAGS+= -V %generate-article-toc% - -# -# SRCS lists the individual SGML files that make up the document. Changes -# to any of these files will force a rebuild -# - -# SGML content -SRCS= article.sgml - -DOC_PREFIX?= ${.CURDIR}/../../.. -.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/committers-guide/article.sgml b/en_US.ISO8859-1/articles/committers-guide/article.sgml deleted file mode 100644 index d36f87a2b4..0000000000 --- a/en_US.ISO8859-1/articles/committers-guide/article.sgml +++ /dev/null @@ -1,2252 +0,0 @@ -<!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; - -<!ENTITY % mailing-lists PUBLIC "-//FreeBSD//ENTITIES DocBook Mailing List Entities//EN"> -%mailing-lists; -]> - -<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.59 2001/04/07 18:22:32 obrien Exp $</pubdate> - - <copyright> - <year>1999</year> - <year>2000</year> - <year>2001</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>developers@FreeBSD.org</email>, - <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> environment - 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.cvshome.org/docs/index.html">http://www.cvshome.org/docs/index.html</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> - - <table frame="none"> - <title>Useful <command>cvs checkout</command> options</title> - - <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> - </table> - - <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 frame="none"> - <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 repository or some other weird - stuff is going on.</para> - - <para>Useful options, in addition to those listed above for - <literal>checkout</literal>:</para> - - <informaltable frame="none"> - <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 frame="none"> - <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.60 2001-04-08 17:26:41 nik 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.60 2001-04-08 17:26:41 nik Exp $</literal> line, leaving the original - <literal>$Id: article.sgml,v 1.60 2001-04-08 17:26:41 nik 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> - - <table frame="none"> - <title>Useful <command>cvs diff</command> options</title> - - <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> - </table> - - <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> - - <table frame="none"> - <title>Useful <command>cvs commit</command> options</title> - - <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> - </table> - - <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> - - <listitem> - <para>Don't leave the <command>cvs commit</command> command in commit - message editing mode for too long (more than 2-3 minutes). It - locks the directory you are working with and will prevent other - developers from committing into the same directory. If you have - to type a long commit message, type it before executing - <command>cvs commit</command>, and insert it into the commit - message.</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>If you have a PGP or GnuPG key, you may want to add it to - <filename>doc/en_US.ISO_8859-1/books/handbook/pgpkeys</filename>. - </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>developers@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> and - <email>developers@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 - categories. 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. Bruce is also very knowledgeable on the various - standards applicable to FreeBSD.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.gallatin;</term> - <term>&a.mjacob;</term> - <term>&a.dfr;</term> - <term>&a.obrien;</term> - - <listitem> - <para>These are the primary developers and overseers of the - DEC Alpha AXP platform.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.dg;</term> - - <listitem> - <para>David is the overseer of the - VM system. If you have a VM system change in mind, - coordinate it with David.</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.obrien;</term> - - <listitem> - <para>David is the unofficial Obersturmbahnfuhrer of - <filename>src/contrib</filename>. If you have something - significant you'd like to do there, you should probably - coordinate it with David first. Please consult him before - importing into <filename>src/contrib</filename> if you have - never done this before in the FreeBSD CVS repository. Also - if you need to commit to something you do not maintain in - <filename>src/contrib</filename> and it is unclear who the - maintainer / point of contact is. (It is also not a bad idea - to consult David if you need to make a non-import commit to - something you maintain in <filename>src/contrib</filename> and - you are new to how FreeBSD does things.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.brian;</term> - - <listitem> - <para>Official maintainer of - <filename>/usr/sbin/ppp</filename>.</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. Garrett is also very knowledgeable on the various - standards applicable to FreeBSD.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.bmah;</term> - - <listitem> - <para>Bruce is keeper of the release notes - (<filename>src/release/texts/*</filename>). If you commit a - change that you think is worthy of mention in the release notes, - please make sure Bruce knows about it. Better still, send him - a patch with your suggested commentary for the release - notes.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.ru;</term> - - <listitem> - <para>Ruslan is Mr mdoc(7). If you are writing a man page and need - some advice on the structure, or the markup, ask Ruslan.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.committers;</term> - - <listitem> - <para>cvs-committers is the entity that CVS 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> - </listitem> - </varlistentry> - - <varlistentry> - <term>&a.developers;</term> - - <listitem> - <para>developers is all committers. This list was created to be a - forum for the committers "community" issues. Examples are Core - voting, announcements, etc... developers@FreeBSD.org is - <emphasis>not</emphasis> intended as a place for code reviews or a - replacement for arch@FreeBSD.org or audit@FreeBSD.org. In fact - using it as such hurts the FreeBSD Project as it gives a sense of a - closed list where general decisions affecting all of the FreeBSD - using community are made with out being "open".</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 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>Respect other contributors.</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. - 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 - maintainer 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 - 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>Respect other contributors.</para> - - <para>You weren't always a committer. At one time you were - a contributor. Remember that at all times. Remember what - it was like trying to get help and attention. Don't forget - that your work as a contributor time was very important to - you. Remember what it was like. Don't discourage, belittle, - or demean contributors. Treat them with respect. They are - our committers in waiting. They are every bit as important - to the project as committers. Their contributions are as - valid and as important as your own. After all, you made - many contributions before you became a committer. Always - remember that. </para> - - <para>Consider the points raised under 'Respect other committers' - and apply them also to contributors.</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 - 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 separate commits that are - clearly labeled as such in the commit message.</para> - </sect2> - </sect1> - - <sect1> - <title>Ports Specific FAQ</title> - - <qandaset> - <qandadiv> - <title>Adding a New Port</title> - - <qandaentry> - <question> - <para>How do I add a new port?</para> - </question> - - <answer> - <para>First, please read the section about repository - copy.</para> - - <para>The easiest way to add a new port is to use the - <command>addport</command> script on - <hostid>freefall</hostid>. It will add a port from the - directory you specify, determining the category automatically - from the port <filename>Makefile</filename>. - It will also add an entry to the - <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 add 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 add 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 - added into a wrong category and is moved immediately, - it suffices to simply <command>cvs remove</command> the - old one and <command>addport</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 an hour or two.</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, 4-stable and 5-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-stable run - /logs all logs from latest 4-stable run - /packages packages from latest 4-stable run - /bak/errors error logs from last complete 4-stable run - /bak/logs all logs from last complete 4-stable run - /bak/packages packages from last complete 4-stable run - /5/errors error logs from latest 5-current run - /logs all logs from latest 5-current run - /packages packages from latest 5-current run - /bak/errors error logs from last complete 5-current run - /bak/logs all logs from last complete 5-current run - /bak/packages packages from last complete 5-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> - - <qandaentry> - <question> - <para>What <quote>meta</quote> information should I include in a - commit message?</para> - </question> - - <answer> - <para>As well as including an informative message with each commit - you may need to include some additional information as - well.</para> - - <para>This information consists of one or more lines containing the - the key word or phrase, a colon, tabs for formatting, and then the - additional information.</para> - - <para>The key words or phrases are:</para> - - <informaltable frame="none"> - <tgroup cols="2"> - <tbody> - <row> - <entry><literal>PR:</literal></entry> - <entry>The problem report (if any) which is affected - (typically, by being closed) by this commit.</entry> - </row> - - <row> - <entry><literal>Submitted by:</literal></entry> - <entry>The name and e-mail address of the person that - submitted the fix.</entry> - </row> - - <row> - <entry><literal>Reviewed by:</literal></entry> - <entry>The name and e-mail address of the person or people - that reviewed the change. If a patch was submitted to a - mailing list for review, and the review was favourable, - then just include the list name.</entry> - </row> - - <row> - <entry><literal>Approved by:</literal></entry> - <entry>The name and e-mail address of the person or people - that approved the change. It is customary to get prior - approval for a commit if it is to an area of the tree to - which you do not usually commit. In addition, during the - run up to a new release all commits - <emphasis>must</emphasis> be approved by the release - engineer. If these are your first commits then you should - have passed them past your mentor first for approval, and - you should list your mentor.</entry> - </row> - - <row> - <entry><literal>Obtained from:</literal></entry> - <entry>The name of the project (if any) from which the code - was obtained.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <example> - <title>Commit log for a commit based on a PR</title> - - <para>You want to commit a change based on a PR submitted by John - Smith containing a patch. The end of the commit message should - look something like this.</para> - - <programlisting>... - -PR: foo/12345 -Submitted by: John Smith <John.Smith@example.com></programlisting> - </example> - - <example> - <title>Commit log for a commit needing review</title> - - <para>You want to change the virtual memory system. You have - posted patches to the appropriate mailing list (in this case, - <literal>freebsd-arch</literal>) and the changes have been - approved.</para> - - <programlisting>... - -Reviewed by: -arch</programlisting> - </example> - - <example> - <title>Commit log for a commit needing approval</title> - - <para>You want to commit a change to a section of the tree with a - MAINTAINER assigned. You have collaborated with the listed - MAINTAINER, who has told you to go ahead and commit. The </para> - - <programlisting>... - -Approved by: <replaceable>abc</replaceable></programlisting> - - <para>Where <replaceable>abc</replaceable> is the account name of - the person who approved.</para> - </example> - - <example> - <title>Commit log for a commit bringing in code from - OpenBSD</title> - - <para>You want to commit some code based on work done in the - OpenBSD project.</para> - - <programlisting>... - -Obtained from: OpenBSD</programlisting> - </example> - - <para>In some cases you may need to combine some of these.</para> - - <para>Consider the situation where a user has submitted a PR - containing code from the NetBSD project. You are looking at the - PR, but it's not an area of the tree you normally work in, so - you've decided to get the change reviewed by the - <literal>arch</literal> mailing list.</para> - - <para>The extra information to include in the commit would look - something like</para> - - <programlisting>PR: foo/54321 -Submitted by: John Smith <John.Smith@example.com> -Reviewed by: -arch -Obtained from: NetBSD</programlisting> - </answer> - </qandaentry> - </qandaset> - </sect1> -</article> |