hi all,
I've been working on a committer guide that goes above and beyond the existing committer FAQ. It is still a work in progress but I thought I'd send it here in the spirit of "release early, release often". Comments, thoughts, help welcome.
cheers,
- Leo
<?xml version="1.0"?>
<document>
<properties>
<title>Committer Guide</title>
</properties>
<body>
<section><title>Introduction</title>
<p>This document is targetted at Apache <em>committers</em>. A committer
is an individual who was given write access to one or more of the
codebases hosted by the ASF. If you are not a committer, you are
probably looking for the <a href="contributors.html">Contributor Tech
Guide</a>.</p>
<p>This document is about the technical means you can use to contribute.
See the <a href="../foundation/contributing.html">ASF Foundation
contribution page</a> for other information, like on how to make a
donation. This document is intended to supersede the
<a href="committers.html">committer FAQ</a> in time. For now, you
should read that FAQ as well.</p>
<ul>
<li><a href="#gettingstarted">Getting Started</a></li>
<li><a href="#environment">Setting up your environment</a></li>
<li><a href="#email">About e-mail</a></li>
<li><a href="#cvs">Working with CVS</a></li>
</ul>
</section>
<section id="gettingstarted"><title>Getting Started</title>
<p>This section details what resources become available to you once you
become a committer, and it details the things you should do when you
become a committer.</p>
<section id="contributoragreement"><title>Sign the Contributor
License Agreement</title>
<p>As soon as you become a committer, you need to complete and
submit (via facsimile or postal mail) a
<a href="http://incubator.apache.org/forms/ASF_Contributor_License_2_form.pdf";
>Contributor Licence Agreement</a> (CLA). The agreement contains
more information.</p>
</section>
<section id="setupaccount"><title>Secure your icarus account</title>
<p>When an ASF project votes you in as a committer, someone on that
project's team (could be you!) contacts root to get you an account
on icarus (the box which runs cvs, among other things).</p>
<p>With this account, you'll be able to log in on the machine
through <a
href="http://directory.google.com/Top/Computers/Security/Products_and_Tools/Cryptography/SSH/";>SSH</a>.
You are getting a full shell account on a BSD machine, which you are
allowed to use for any ASF purpose, but please be conservative with
disk space and other resources.</p>
<p>The first thing you should do is change your password. The
example below assumes you use a unix system or you have cygwin
properly setup on your machine (see below).</p>
<p>Open up a shell/console window, and enter the following:</p>
<pre>
ssh [EMAIL PROTECTED]
# you are asked to enter the password root e-mailed you
passwd
# you are asked to enter your current password, then a new one (twice)
# logout again
exit
</pre>
<p>choose a good password (minimum 8 characters, containing at least
one capital and one lowercase letter, one number and one
non-alphanumeric character. Store it in a safe place. You are
responsible for remembering this password and keeping it safe.</p>
<p>You should normally never actually use this password for logging
in; rather, you are required to use <a
href="http://www.onlamp.com/pub/a/onlamp/excerpt/ssh_8/";>public key
authentication</a>. Again assuming you are on cygwin or unix, here's
how to set these up:</p>
<pre>
# generated the key:
ssh-keygen -b 1024 -t rsa
# hit enter to accept the default location, then enter a password to
# secure the public key (twice)
# copy the public key to the icarus machine:
scp ~/.ssh/id_rsa.pub \
[EMAIL PROTECTED]:~/.ssh/authorized_keys
# enter your password (the machine password, not that of your SSH key)
# test it works
ssh -v [EMAIL PROTECTED]
# logout again
exit
</pre>
<p>If things go allright, you are asked to enter your public key
password, after which you will be logged in. If things don't go
correctly, contact the infrastructure mailing list (see below) with
all relevant info. In particular, make sure to describe exactly what
steps you took, and include the output of the ssh -v (-v for
verbose) command.</p>
<p>If you have been given accounts on other apache machines, change
the passwords on those as well using the same commands, then copy
your public key to those machines as well:</p>
<pre>
scp ~/.ssh/id_rsa.pub \
[EMAIL PROTECTED]:~/.ssh/authorized_keys
</pre>
<p>Note it is very important that your SSH private key remains
totally private. Never give it out to anyone.</p>
</section>
<section><title>Add yourself as a committer</title>
<p>Update your project's website to reflect the fact that you are
now a committer to that project.</p>
</section>
<section><title>Review project guidelines</title>
<p>Make sure you are up-to-date on the way your project handles
stuff like voting, what your project's coding standards are, etc
etc. Work is underway to "streamline" the information about this
across the different apache projects. Until we're done
(help wanted!), your best bet is to take a look at the
<a href="http://incubator.apache.org/drafts/index.html";>Incubator
documentation drafs</a>, the <a href="http://httpd.apache.org/dev/";
>HTTPD development information</a> pages and the
<a href="http://jakarta.apache.org/site/guidelines.html";>Jakarta
project guidelines</a>.</p>
</section>
</section>
<section id="email"><title>About e-mail</title>
<section><title>[EMAIL PROTECTED]</title>
<p>Along with your icarus account, you get an apache e-mail address.
You should read the messages sent here. The easiest thing to do is
to have the e-mail sent here forwarded to another e-mail address,
though you can also use <a
href="http://www.washington.edu/pine/";>Pine</a> on icarus. Here's
how to set up mail forwarding:</p>
<pre>
ssh [EMAIL PROTECTED]
echo '[EMAIL PROTECTED]' > .forward
exit
</pre>
<p>That simple :D. There's no "official" policy on how you should
or should not use your apache e-mail address; it is expected of you
that you behave responsibly and don't abuse it in any way like for
sending spam.</p>
</section>
<section><title>Mailing Lists</title>
<p>There's a few mailing lists open only to apache committers
(though some exceptions may be made):</p>
<section><title>[EMAIL PROTECTED]</title>
<p>The infrastructure mailing list is where the people who manage
the ASF infrastructure hang out and get things done. All interested
committers are invited to join. You will often want to CC this list
if you request something from the apcvs or apmail or root people.
It's also where you should send patches for this document :D.
Subscribe by sending an e-mail to
[EMAIL PROTECTED] Please be nice to these guys;
they do some great work.</p>
</section>
<section><title>[EMAIL PROTECTED]</title>
<p>All committers are required to subscribe to this list (and your
committer e-mail address is automatically subscribed). It is used
for important announcements only. Don't go chattering away here.</p>
</section>
<section><title>More mailing lists</title>
<p>See <a href="http://www.apache.org/foundation/mailinglists.html";
>this page</a> for what should be a full list. Some more ASF-wide
lists include [email protected] and [EMAIL PROTECTED] Both are
neat to be on as you get to know people that way.</p>
</section>
</section>
<section><title>Whom to contact</title>
<p>There's quite a few special mailing lists or mail groups for
various things @ apache. Here's a few important addresses:</p>
<ul>
<li>[EMAIL PROTECTED] - in case of security problems, account
creation requests, or anything else the root (administrator) should
do or know about</li>
<li>[EMAIL PROTECTED] - in case of mailing list configuration
change requests</li>
<li>[EMAIL PROTECTED] - in case of cvs configuration change
requests</li>
</ul>
</section>
<section><title>More on e-mail</title>
<a href="http://www.apache.org/dev/list-setup.html";>Mailing list
setup</a>
</section>
</section>
<section id="environment"><title>Setting up your environment</title>
<p>If you run unix, you probably know your way around so no details
provided here. The basic things you need to be productive for apache are
an SSH client, a way to read e-mail, a web browser and software
development tools (Duh!). The rest of this section is mostly for
windoze people.</p>
<section><title>Cygwin</title>
<p><a href="http://www.cygwin.com/";>Cygwin</a> is a UNIX environment
for windows. It provides many useful unix tools, like bash and ssh.
I highly recommend you install it if you haven't already. It makes
life much much easier.
<a href="http://www.cygwin.com/setup.exe";>Click Here</a> to install
it right now. Make sure to install bash, SSH, perl and python (all
installed by default I think), at a minimum.</p>
</section>
<section><title>CVSUtils</title>
<p><a href="http://www.red-bean.com/cvsutils/";>CVSUtils</a> is a set
of perl scripts that allow you to do some powerful things with CVS.
Get it, read the docs.</p>
</section>
<section><title>C Development</title>
<p>You'll need tools like make, automake, autoconf, gcc. Make sure
you have them all.</p>
</section>
<section><title>Java Development</title>
<p>You should get yourself the latest versions of
<a href="http://ant.apache.org/";>Apache Ant</a>,
<a href="http://jakarta.apache.org/turbine/maven";>Maven</a>,
<a href="http://jakarta.apache.org/site/jakarta-site2.html";
>Anakia</a>,
<a href="http://xml.apache.org/forrest/";>Forrest</a>,
<a href="http://www.krysalis.org/centipede/";>Krysalis Centipede</a>
and <a href="http://www.junit.org/";>JUnit</a>. Also get yourself a
decent IDE, like VIM, Emacs, JEdit, Eclipse, NetBeans, or something
commercial like IDEA. Read <a
href="http://jakarta.apache.org/site/idedevelopers.html";>The IDE
Developers Guide</a> if you're an IDE developer.</p>
</section>
</section>
<section id="cvs"><title>Working with CVS</title>
<p>Before you start here, it is expected you are already familiar with
CVS basics (see the
<a href="contributors.html">Contributor Tech Guide</a> if you're not)
and it's purpose.</p>
<section><title>CVS over SSH</title>
<p>All communication with the CVS server should go through a secure
SSH tunnel. I would like to integrate <a
href="http://xml.apache.org/forrest/community/howto/cvs-ssh/howto-cvs-ssh.html";
>the forrest howto on CVS+SSH</a>, but just read that until someone
does. If you still have questions after that or it doesn't work,
try <a href="http://jakarta.apache.org/site/cvsindex.html";>the
Jakarta Project page on CVS</a>.</p>
</section>
<section><title>Changing the repository root</title>
<p>If you have checkouts of apache repositories through anoncvs,
you normally need to check out fresh copies in order to be able to
modify them. You can also 'hack' your local copy to avoid
downloading all those megs:</p>
<pre>
% cd <i>your-project-working-directory</i>
% find . -type d -name CVS \
> | perl -pe 's,(.*CVS$),$1/Root,' \
> | xargs perl -pi -e \
> 's,:pserver:anoncvs(.+:/home/cvs)public,:ext:<i>your-username</i>$1,'
% cvs -q update -dP
</pre>
<p>I told you you'd need perl :D</p>
</section>
<section><title>Moving CVS files</title>
<p>There is no builtin way to move files in a CVS repository while
keeping their history. You can hack the CVS repository though (make
sure you know what you're doing!). Here's some sample commands I
once used to move a complete directory with all contents:</p>
<pre>
#######################################
ssh [EMAIL PROTECTED] # ssh to apache cvs box
# for file permissions, just paranoia -- as you use the -p switch for cp
umask 002
# new location for the CVS/RCS files
cd /home/cvs/avalon-sandbox
# copy the old RCS structure you want to move here, preserving permissions
# this is the only bit of 'magic' where you work around cvs limitations.
cp -Rp ../jakarta-avalon/src/proposal/avalon5 .
exit # back to local box
# nothing fancy here, just removing the old materials using std cvs commands.
# Could use a GUI client here if you wanted.
cd ~/projects/avalon/jakarta-avalon/src/proposal/
cvs tag -R PRE_MOVE_TO_SANDBOX avalon5/
cvs remove -R -f avalon5
cvs commit -R -m 'removal explanation' avalon5
cvs up -P -d
# tags that existed in the old structure might conflict with those in the
# new structure. If you wish to make sure that is not a problem, you can
# remove all tags in the existing location. Again, just standard cvs commands.
# Could use a GUI client here if you wanted.
cd ../avalon-sandbox
cvs update -P -d
cd avalon5
cvs log > cvs_history.txt # get cvs logs
cvs tag -R -d SOME_TAG avalon5 # repeat this for all existing tags
cvs add cvs_history.txt
cvs commit -m "history up to $currentdate, including tags" \
cvs_history.txt
cvs remove -f cvs_history.txt
cvs commit -m 'move history to attic' cvs_history.txt
#######################################
</pre>
</section>
<section><title>More on CVS</title>
<p>I recommend you read
<a href="http://www.red-bean.com/cvsbook/";>The CVS Book</a> cover
to cover.</p>
</section>
</section>
</body>
</document>
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
