www-community mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Daniel Rall <...@collab.net>
Subject Re: committer guide for www.apache.org/dev/
Date Sat, 08 Mar 2003 00:53:55 GMT
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 <leosimons@apache.org> 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 ${your-account-name}@icarus.apache.org
> # 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 \
>     ${your-account-name}@icarus.apache.org:~/.ssh/authorized_keys
> # enter your password (the machine password, not that of your SSH key)
> 
> # test it works
> ssh -v ${your-account-name}@icarus.apache.org
> 
> # 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 \
>     ${your-account-name}@${machine}.apache.org:~/.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>${your-account-name}@apache.org</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 ${your-account-name}@icarus.apache.org
> echo 'your-email-address@domain.com' > .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>infrastructure@apache.org</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
>     infrastructure-subscribe@apache.org. Please be nice to these guys;
>     they do some great work.</p> 
>     
>     </section>
>     
>     <section><title>committers@apache.org</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 community@apache.org and party@apache.org. 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>root@apache.org - in case of security problems, account
>     creation requests, or anything else the root (administrator) should
>     do or know about</li>
>     <li>apmail@apache.org - in case of mailing list configuration
>     change requests</li>
>     <li>apcvs@apache.org - 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 leosimons@cvs.apache.org # 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 <dlr@finemaltcoding.com>

---------------------------------------------------------------------
To unsubscribe, e-mail: community-unsubscribe@apache.org
For additional commands, e-mail: community-help@apache.org


Mime
View raw message