Add a manual page outlining the rules for committers.
authorMatthew Dillon <dillon@dragonflybsd.org>
Sun, 3 Dec 2006 20:28:07 +0000 (20:28 +0000)
committerMatthew Dillon <dillon@dragonflybsd.org>
Sun, 3 Dec 2006 20:28:07 +0000 (20:28 +0000)
share/man/man8/committer.8 [new file with mode: 0644]

diff --git a/share/man/man8/committer.8 b/share/man/man8/committer.8
new file mode 100644 (file)
index 0000000..6a5c29f
--- /dev/null
@@ -0,0 +1,214 @@
+.\" Copyright (c) 2003,2004 The DragonFly Project.  All rights reserved.
+.\" 
+.\" This code is derived from software contributed to The DragonFly Project
+.\" by Matthew Dillon <dillon@backplane.com>
+.\" 
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in
+.\"    the documentation and/or other materials provided with the
+.\"    distribution.
+.\" 3. Neither the name of The DragonFly Project nor the names of its
+.\"    contributors may be used to endorse or promote products derived
+.\"    from this software without specific, prior written permission.
+.\" 
+.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
+.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
+.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
+.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\" 
+.\" $DragonFly: src/share/man/man8/Attic/committer.8,v 1.1 2006/12/03 20:28:07 dillon Exp $
+.\" 
+.Dd December 3, 2006
+.Dt COMMITTER 8
+.Os
+.Sh NAME
+.Nm committer
+.Nd Rules for
+.Dx
+committers
+.Sh CVS REPOSITORY ON YOUR LOCAL MACHINE
+Use cvsup to mirror the CVS repository itself onto your local box
+(if you haven't already).  See the file 
+/usr/share/examples/cvsup/DragonFly-cvs-supfile
+.Pp
+You basically want to do all cvs operations not related to commits
+via your local repository, and do commit operations directly to
+the master site.
+.Pp
+I strongly recommend that you set up a cron job to automatically
+cvsup at least once a day, so your local cvs repository is always
+in sync.
+.Sh CHECKING OUT THE SOURCES
+Your ~/.cvsrc should contain:
+.Bd -literal -offset indent
+cvs -q
+diff -u
+update -Pd
+checkout -P
+.Ed
+Checking out and updating a checked out source tree:
+.Bd -literal -offset indent
+cd /usr
+cvs -d /home/dcvs checkout src
+cvs -d /home/dcvs update src
+.Ed
+.Pp
+We do *NOT* recommend that you use a cron job to cvs update your
+checked out source.  Automatic cvs updates can interfere with 
+any work-in-progress that you have.
+.Sh SSH DSA KEYS:
+The CVS repository machine is "crater.dragonflybsd.org", and the 
+DragonFly developer machine is "leaf.dragonflybsd.org".  We create
+an account for you on both machines and install your public SSH
+key to give you access.
+.Pp
+Your crater account is set up for CVS repository only... it can
+only operate as a CVS slave, it cannot be logged into.  That is,
+crater.dragonflybsd.org is only used as part of cvs -d ... operations.
+.Pp
+Your leaf account is a general developer account.  Any DragonFly
+developer can have a leaf account, whether a committer or not.
+It can be useful as a developer rendezvous,
+however.  For example, people upload kernel cores to leaf so other
+developers can look at them.  You log into your leaf account with:
+.Pp
+.Li ssh you@leaf.dragonflybsd.org
+.Pp
+The rules for account use are in leaf's MOTD. 
+It is very important that you never install a password or create a SSH
+key pair on leaf to use to access other machines.
+Because non-committers can have leaf accounts, leaf is not considered
+a secure machine. 
+.Sh TESTING COMMIT ACCESS
+There is a directory called /usr/src/test/test.  To test your commit
+access, try making a modification and commiting a file in this
+directory.
+.Pp
+.Bd -literal -offset indent
+cd /usr/src/test/test
+(edit something)
+cvs -d you@crater.dragonflybsd.org commit file_you_edited
+.Ed
+.Sh COMITTING REAL WORK
+Make modifications as needed.  For example, edit files.  If adding
+new files make CVS aware of them like this.  Files can just be 
+added locally, but directories have to run through crater.  These
+operations do not actually effect the repository (except directories
+being added are mkdir'd in the repository).  Instead they are
+stored in the checkout source's CVS/ sub directory and then 
+synchronized to the repository when you cvs commit.
+.Pp
+.Bd -literal -offset indent
+cvs add filename
+cvs -d you@crater.dragonflybsd.org:/cvs add directory
+.Ed
+.Pp
+To commit to the repository, use:
+.Bd -literal -offset indent
+cvs -d you@crater.dragonflybsd.org:/cvs commit files_or_directories
+.Ed
+.Pp
+.It
+Do not set CVSROOT to you@crater.dragonflybsd.org:/cvs.  The
+reason is that you want the default CVSROOT in your checked out
+sources to point at your local cvs repository, not at crater.
+This reduces instances where accidental commits or repository
+operations are made on crater.
+.Pp
+It is best to avoid cvs update'ing directly from the repository.
+e.g. try to avoid doing 'cvs -d ... update' directly from crater.
+Instead, use cvsup to resync your local copy of the repository
+and use 'cvs update' or 'cvs -d /home/dcvs update' to update from
+your local copy of the repository.
+.Pp
+The idea here is to try to avoid having CVS set its CVS/Root
+file in any given checked out cvs directory to point at crater.
+You really want it to just point at your local copy of the cvs
+repository.
+.It
+Never do cvs tag or rtag operations.  Such operations can be
+very dangerous and only highly experienced CVS admins should
+do them.  That's basically just two or three people (Me and Joerg
+primarily).
+.It
+The best way to resynchronize your local cvs repository after
+making a commit is to cvsup again.
+.Sh DISCUSSING COMMITTABLE WORK BEFORE HAND
+Discussion prior to commit usually occurs on the kernel@, submit@, or bugs@
+mailing list.  It depends on the work involved.  Simple and obvious work, 
+such as documentation edits or additions, don't really need a head's up.
+.Pp
+Simple and obvious bug fixes don't need a head's up, other then to
+say that you will (or just have) committed the fix, so you don't
+race other committers trying to do the same thing.  Usually the
+developer most active in a discussion about a bug commits the
+fix, but it isn't considered a big deal.
+.Pp
+More complex issues are usually discussed on the lists first.
+Non-trivial but straight forward bug fixes usually go through
+a testing period, where you say something like: "Here is a patch
+to driver BLAH that fixes A, B, and C, please test it.  If there
+are no objections I will commit it next Tuesday" (usually a week,
+or more depending on the complexity of the patch).
+.Pp
+New drivers or utilities are usually discussed.  Committers will
+often commit new work *without* hooking it into the buildworld or
+buildkernel infrastructure in order to be able to continue 
+development on it in piecemeal without having to worry about it
+breaking buildworld or buildkernel, and then they hook it in as a
+last step after they've stabilized it.  Examples of this include
+new versions of GCC, updates to vendor packages such as bind,
+sendmail, etc.
+.Pp
+.Sh DEVELOPER LOCKS
+Areas within the CVS repository are never explicitly locked.
+Often situations will arise where one developer commits work and
+another developer finds an issue with it that needs to be corrected.
+.Pp
+All committed work becomes community property.  No developer has a
+'lock' on any part of the source tree.  However, if a developer is
+actively working on a portion of the source tree and you find a bug
+or other issue, courtesy dictates that you post to kernel@ and/or
+email the developer.
+.Pp
+This means that, generally, if you do not see a commit to an area
+of the source tree in the last few weeks, it isn't considered active and
+you don't really need to confer with the developer that made the
+commit, though you should still post to the kernel@ mailing list
+and, of course, confer with developers when their expertise is
+needed.
+.Pp
+One exception to this rule is documentation.  If any developer commits
+new work, the documentation guys have free reign to go in and
+correct MDOC errors.  This is really a convenience... most developers
+are not MDOC gurus and its a waste of time for the doc guys to post
+to kernel@ for all the little corrections they make.
+.Sh CONFLICTS
+On the occassion that a major code conflict occurs, for example if two
+people are doing major work in the same area of the source tree and forgot
+to collaborate with each other, the project leader will be responsible for
+resolving the conflict.  Again, the repository is considered community
+property and it must be acceptable for any developer to be able to work on
+any area of the tree that he or she has an interest in.
+.Sh MAJOR ARCHITECTURAL CHANGES
+This is generally my area of expertise.  All major architectural
+changes must be discussed on the kernel@ mailing list and I retain
+veto power.
+.Pp
+This isn't usually an issue with any work.  At best if something
+doesn't look right architecturally I chip in with adjustments to
+make it fit in.  Nothing ever really gets vetoed.