Leo, was this committed? Should it be? Does it replace the committer FAQ? I'm not in favor of adding yet another document, I'd like to see'em merged.
- Dan Leo Simons <[EMAIL PROTECTED]> writes: > 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> > > -- Daniel Rall <[email protected]> --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
