The FreeBSD New Committer's Guide. The original text version was worked

on by many people, the SGML conversion has been carried out by the new(ish)
committer, John Baldwin.  Cheer's John.

Changes from the submission:

  1.  It's an article, not a book.  I originally thought there was going
      to be sufficient content (when you include the committers rules
      that are being thrashed out at the moment, and Satoshi's ports
      committer stuff) to make this worth being a book.  After seeing the
      content I changed my mind, so it's an article.

  2.  Various contractions ("you're" and so on) expanded to make life
      a little easier for the translators.  Kept one ("Who's Who").

1 files changed, 404 insertions, 0 deletions

diff --git a/en_US.ISO_8859-1/articles/committers-guide/article.sgml b/en_US.ISO_8859-1/articles/committers-guide/article.sgml
new file mode 100644
index 0000000000..17533ba308
--- /dev/null
+++ b/en_US.ISO_8859-1/articles/committers-guide/article.sgml
@@ -0,0 +1,404 @@
+<!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>New Committer Guide</title>
+
+    <authorgroup>
+      <author>
+	<surname>The FreeBSD Documentation Project</surname>
+      </author>
+    </authorgroup>
+
+    <pubdate>September 1999</pubdate>
+
+    <copyright>
+      <year>1999</year>
+      <holder>The FreeBSD Documentation Project</holder>
+    </copyright>
+
+    <abstract>
+      <para>Welcome, new committer, to the FreeBSD development
+	team!</para>
+
+      <para>The following docs are provided to orient you on doing CVS
+	operations on the FreeBSD central repository machine.  A basic
+	familiarity with CVS is already assumed, although CVS
+	reference information, tutorials, and FAQs can also be found
+	at: <ulink url="http://www.cyclic.com/cyclic-pages/books.html">http://www.cyclic.com/cyclic-pages/books.html</ulink></para>
+
+      <para>Good luck, and welcome aboard!</para>
+    </abstract>
+  </artheader>
+
+  <sect1 id="admin">
+    <title>Administrative Details</title>
+
+    <informaltable frame="none" orient="port">
+      <tgroup cols="2">
+	<tbody>
+	  <row>
+	    <entry><emphasis>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>CVSROOT</emphasis></entry>
+	    <entry>/home/ncvs</entry>
+	  </row>
+	  
+	  <row>
+	    <entry><emphasis>CVS Repository Meisters</emphasis></entry>
+	    <entry>&a.jdp; and &a.peter;</entry>
+	  </row>
+	  
+	  <row>	  
+	    <entry><emphasis>Mailing List</emphasis></entry>
+	    <entry><email>cvs-committers@FreeBSD.org</email>
+	      [which you are now on]</entry>
+	  </row>
+	  
+	  <row>	  
+	    <entry><emphasis>Mentor Name</emphasis></entry>
+	    <entry>&a.jkh;</entry>
+	  </row>
+	  
+	  <row>	  
+	    <entry><emphasis>Noteworthy CVS Tags</emphasis></entry>
+	    <entry>RELENG_3 (3.x-STABLE), HEAD (-CURRENT)</entry>
+	  </row>
+	</tbody>
+      </tgroup>
+    </informaltable>
+    
+    <para>It is required that you use &man.ssh.1; with public key
+      authentication to access the repository host.  This is generally
+      more secure than &man.telnet.1; or &man.rlogin.1; since your
+      connection will always be encrypted.  With utilities like
+      &man.ssh-agent.1; and &man.scp.1; also available, it 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>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 new ports, 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. &ndash; just run it without
+      arguments and it will prompt you for everything it needs to
+      know.</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>
+  </sect1>
+
+  <sect1 id="conventions">
+    <title>Conventions and Traditions</title>
+
+    <para>The CVS Repository Meisters (Peter Wemm and John Polstra)
+      are the <quote>owners</quote> of the CVS repository and
+      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.</para>
+
+    <para>If you are a new committer, your very first commit should be
+      to add yourself to the developer's section (28.2) of the
+      Handbook.  Figuring out how to check the handbook out and add an
+      entry for yourself is relatively easy but still remains a good
+      first test of your CVS skills.  If you can handle that one,
+      you are probably going to be ok.</para>
+
+    <para>Your next step should be to 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>
+
+    <para>Also, be sure to log into <hostid>hub.FreeBSD.org</hostid>
+      and create yourself a
+      <filename>/var/forward/<replaceable>user</replaceable></filename>
+      (where <replaceable>user</replaceable> is your username) file
+      which contains your principal e-mail address where you want mail
+      to <replaceable>yourusername</replaceable>@FreeBSD.org
+      to be forwarded.  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>
+
+    <para>All new committers also have a mentor assigned to them for
+      the first few months.  The name of your mentor listed at the top
+      of this message.  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-all</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. 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 at all unsure about a commit for any reason in
+      general, have it reviewed by <literal>-hackers</literal> first
+      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 &ndash; 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>
+  </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 new role as a committer.  Briefly,
+    and by no means all-inclusively, these are:</para>
+
+    <variablelist>
+      <varlistentry>
+	<term>&a.asami;</term>
+	
+	<listitem>
+	  <para>Is the portsmeister, meaning that he has ultimate
+	  authority during code freezes over any modifications to the
+	  ports collection or ports make macro files.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>&a.bde;</term>
+	
+	<listitem>
+	  <para>Is Obersturmbahnfuhrer of the Style Police.  When you
+	    do a commit that could have been done better, Bruce will
+	    be there to note it to you.  Be thankful that someone
+	    is.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>&a.dg;</term>
+	
+	<listitem>
+	  <para>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
+	    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 can also occasionally be
+	    necessary.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>&a.jkh;</term>
+	
+	<listitem>
+	  <para>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 unofficial maintainer of
+	    <filename>/usr/src/bin</filename>.  If you have something
+	    significant you'd like to do there, you should probably
+	    coordinate it first with Steve.  He's also 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>Update and install the ssh port in
+	  <filename>/usr/ports/security/ssh</filename> (should be
+	  version 1.2.25 or later).</para>
+      </step>
+
+      <step>
+	<para>Make sure that you run &man.ssh-agent.1; 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>Copy your public key
+	  (<filename><envar>$HOME</envar>/.ssh/identity.pub</filename>)
+	  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;) so that you won't
+      have to retype it over and over.</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/ssh</filename>, &man.ssh.1;,
+      &man.ssh-agent.1;, &man.scp.1;, and &man.ssh-keygen.1;.</para>
+  </sect1>
+</article>