From ec22575ac966157d31957c9a6af53024b9cea920 Mon Sep 17 00:00:00 2001 From: Matthew Dillon Date: Sun, 3 Dec 2006 20:28:07 +0000 Subject: [PATCH] Add a manual page outlining the rules for committers. --- share/man/man8/committer.8 | 214 +++++++++++++++++++++++++++++++++++++ 1 file changed, 214 insertions(+) create mode 100644 share/man/man8/committer.8 diff --git a/share/man/man8/committer.8 b/share/man/man8/committer.8 new file mode 100644 index 0000000000..6a5c29f4d8 --- /dev/null +++ b/share/man/man8/committer.8 @@ -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 +.\" +.\" 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. -- 2.41.0