1.\" Copyright (c) 2003,2004 The DragonFly Project. All rights reserved. 2.\" 3.\" This code is derived from software contributed to The DragonFly Project 4.\" by Matthew Dillon <dillon@backplane.com> 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in 14.\" the documentation and/or other materials provided with the 15.\" distribution. 16.\" 3. Neither the name of The DragonFly Project nor the names of its 17.\" contributors may be used to endorse or promote products derived 18.\" from this software without specific, prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 21.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 22.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 23.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 24.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 25.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, 26.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 27.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 28.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 29.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 30.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31.\" SUCH DAMAGE. 32.\" 33.\" $DragonFly: src/share/man/man7/committer.7,v 1.2 2006/12/03 21:15:27 swildner Exp $ 34.\" 35.Dd December 3, 2006 36.Dt COMMITTER 7 37.Os 38.Sh NAME 39.Nm committer 40.Nd Rules for 41.Dx 42committers 43.Sh CVS REPOSITORY ON YOUR LOCAL MACHINE 44Use cvsup to mirror the CVS repository itself onto your local box 45(if you haven't already). See the file 46/usr/share/examples/cvsup/DragonFly-cvs-supfile 47.Pp 48You basically want to do all cvs operations not related to commits 49via your local repository, and do commit operations directly to 50the master site. 51.Pp 52I strongly recommend that you set up a cron job to automatically 53cvsup at least once a day, so your local cvs repository is always 54in sync. 55.Sh CHECKING OUT THE SOURCES 56Your ~/.cvsrc should contain: 57.Bd -literal -offset indent 58cvs -q 59diff -u 60update -Pd 61checkout -P 62.Ed 63Checking out and updating a checked out source tree: 64.Bd -literal -offset indent 65cd /usr 66cvs -d /home/dcvs checkout src 67cvs -d /home/dcvs update src 68.Ed 69.Pp 70We do *NOT* recommend that you use a cron job to cvs update your 71checked out source. Automatic cvs updates can interfere with 72any work-in-progress that you have. 73.Sh SSH DSA KEYS: 74The CVS repository machine is "crater.dragonflybsd.org", and the 75DragonFly developer machine is "leaf.dragonflybsd.org". We create 76an account for you on both machines and install your public SSH 77key to give you access. 78.Pp 79Your crater account is set up for CVS repository only... it can 80only operate as a CVS slave, it cannot be logged into. That is, 81crater.dragonflybsd.org is only used as part of cvs -d ... operations. 82.Pp 83Your leaf account is a general developer account. Any DragonFly 84developer can have a leaf account, whether a committer or not. 85It can be useful as a developer rendezvous, 86however. For example, people upload kernel cores to leaf so other 87developers can look at them. You log into your leaf account with: 88.Pp 89.Li ssh you@leaf.dragonflybsd.org 90.Pp 91The rules for account use are in leaf's MOTD. 92It is very important that you never install a password or create a SSH 93key pair on leaf to use to access other machines. 94Because non-committers can have leaf accounts, leaf is not considered 95a secure machine. 96.Sh TESTING COMMIT ACCESS 97There is a directory called /usr/src/test/test. To test your commit 98access, try making a modification and commiting a file in this 99directory. 100.Pp 101.Bd -literal -offset indent 102cd /usr/src/test/test 103(edit something) 104cvs -d you@crater.dragonflybsd.org commit file_you_edited 105.Ed 106.Sh COMITTING REAL WORK 107Make modifications as needed. For example, edit files. If adding 108new files make CVS aware of them like this. Files can just be 109added locally, but directories have to run through crater. These 110operations do not actually effect the repository (except directories 111being added are mkdir'd in the repository). Instead they are 112stored in the checkout source's CVS/ sub directory and then 113synchronized to the repository when you cvs commit. 114.Pp 115.Bd -literal -offset indent 116cvs add filename 117cvs -d you@crater.dragonflybsd.org:/cvs add directory 118.Ed 119.Pp 120To commit to the repository, use: 121.Bd -literal -offset indent 122cvs -d you@crater.dragonflybsd.org:/cvs commit files_or_directories 123.Ed 124.Pp 125Do not set CVSROOT to you@crater.dragonflybsd.org:/cvs. The 126reason is that you want the default CVSROOT in your checked out 127sources to point at your local cvs repository, not at crater. 128This reduces instances where accidental commits or repository 129operations are made on crater. 130.Pp 131It is best to avoid cvs update'ing directly from the repository. 132e.g. try to avoid doing 'cvs -d ... update' directly from crater. 133Instead, use cvsup to resync your local copy of the repository 134and use 'cvs update' or 'cvs -d /home/dcvs update' to update from 135your local copy of the repository. 136.Pp 137The idea here is to try to avoid having CVS set its CVS/Root 138file in any given checked out cvs directory to point at crater. 139You really want it to just point at your local copy of the cvs 140repository. 141.Pp 142Never do cvs tag or rtag operations. Such operations can be 143very dangerous and only highly experienced CVS admins should 144do them. That's basically just two or three people (Me and Joerg 145primarily). 146.Pp 147The best way to resynchronize your local cvs repository after 148making a commit is to cvsup again. 149.Sh DISCUSSING COMMITTABLE WORK BEFORE HAND 150Discussion prior to commit usually occurs on the kernel@, submit@, or bugs@ 151mailing list. It depends on the work involved. Simple and obvious work, 152such as documentation edits or additions, don't really need a head's up. 153.Pp 154Simple and obvious bug fixes don't need a head's up, other then to 155say that you will (or just have) committed the fix, so you don't 156race other committers trying to do the same thing. Usually the 157developer most active in a discussion about a bug commits the 158fix, but it isn't considered a big deal. 159.Pp 160More complex issues are usually discussed on the lists first. 161Non-trivial but straight forward bug fixes usually go through 162a testing period, where you say something like: "Here is a patch 163to driver BLAH that fixes A, B, and C, please test it. If there 164are no objections I will commit it next Tuesday" (usually a week, 165or more depending on the complexity of the patch). 166.Pp 167New drivers or utilities are usually discussed. Committers will 168often commit new work *without* hooking it into the buildworld or 169buildkernel infrastructure in order to be able to continue 170development on it in piecemeal without having to worry about it 171breaking buildworld or buildkernel, and then they hook it in as a 172last step after they've stabilized it. Examples of this include 173new versions of GCC, updates to vendor packages such as bind, 174sendmail, etc. 175.Pp 176.Sh DEVELOPER LOCKS 177Areas within the CVS repository are never explicitly locked. 178Often situations will arise where one developer commits work and 179another developer finds an issue with it that needs to be corrected. 180.Pp 181All committed work becomes community property. No developer has a 'lock' 182on any part of the source tree. However, if a developer is 183actively working on a portion of the source tree and you find a bug 184or other issue, courtesy dictates that you post to kernel@ and/or 185email the developer. 186.Pp 187This means that, generally, if you do not see a commit to an area 188of the source tree in the last few weeks, it isn't considered active and 189you don't really need to confer with the developer that made the 190commit, though you should still post to the kernel@ mailing list 191and, of course, confer with developers when their expertise is 192needed. 193.Pp 194One exception to this rule is documentation. If any developer commits 195new work, the documentation guys have free reign to go in and 196correct MDOC errors. This is really a convenience... most developers 197are not MDOC gurus and its a waste of time for the doc guys to post 198to kernel@ for all the little corrections they make. 199.Sh CONFLICTS 200On the occassion that a major code conflict occurs, for example if two 201people are doing major work in the same area of the source tree and forgot 202to collaborate with each other, the project leader will be responsible for 203resolving the conflict. Again, the repository is considered community 204property and it must be acceptable for any developer to be able to work on 205any area of the tree that he or she has an interest in. 206.Sh MAJOR ARCHITECTURAL CHANGES 207This is generally my area of expertise. All major architectural 208changes must be discussed on the kernel@ mailing list and I retain 209veto power. 210.Pp 211This isn't usually an issue with any work. At best if something 212doesn't look right architecturally I chip in with adjustments to 213make it fit in. Nothing ever really gets vetoed. 214