432 lines
16 KiB
Text
432 lines
16 KiB
Text
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" [
|
|
<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
|
|
%man;
|
|
|
|
<!ENTITY % authors PUBLIC "-//FreeBSD//ENTITIES DocBook Author Entities//EN">
|
|
%authors;
|
|
]>
|
|
|
|
<article>
|
|
<artheader>
|
|
<title>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>Main Repository Host</emphasis></entry>
|
|
<entry><hostid>freefall.FreeBSD.org</hostid></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>
|
|
<emphasis>International Crypto Repository Host</emphasis>
|
|
</entry>
|
|
<entry><hostid>internat.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>International Crypto CVSROOT</emphasis></entry>
|
|
<entry>/home/cvs.crypt</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><emphasis>Main CVS Repository Meisters</emphasis></entry>
|
|
<entry>&a.jdp; and &a.peter;</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>
|
|
<emphasis>International Crypto CVS Repository Meister</emphasis>
|
|
</entry>
|
|
<entry>&a.markm;</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. – 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 – 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.markm;</term>
|
|
<listitem>
|
|
<para>Mark is the CVS repository meister for the
|
|
international cypto repository kept on
|
|
<hostid>internat.FreeBSD.org</hostid>.</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>
|