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.9 2007/12/23 15:31:29 swildner Exp $ 34.\" 35.Dd January 1, 2007 36.Dt COMMITTER 7 37.Os 38.Sh NAME 39.Nm committer 40.Nd rules for DragonFly committers 41.Sh CVS REPOSITORY ON YOUR LOCAL MACHINE 42Use 43.Xr cvsup 1 44to mirror the 45.Dx 46CVS repository itself onto your local box 47(if you haven't already). See the file 48.Pa /usr/share/examples/cvsup/DragonFly-cvs-supfile . 49.Pp 50You basically want to do all CVS operations not related to commits 51via your local repository, and do commit operations directly to 52the master site. 53.Pp 54We strongly recommend that you set up a 55.Xr cron 8 56job to automatically 57cvsup at least once a day, so your local CVS repository is always 58in sync. 59.Sh CHECKING OUT THE SOURCES 60Your 61.Pa ~/.cvsrc 62should contain: 63.Bd -literal -offset indent 64cvs -q 65diff -u 66update -Pd 67checkout -P 68.Ed 69.Pp 70Checking out and updating a checked out source tree: 71.Bd -literal -offset indent 72cd /usr 73cvs -d /home/dcvs checkout src 74cvs -d /home/dcvs update src 75.Ed 76.Pp 77We do 78.Em NOT 79recommend that you use a cron job to 80.Nm cvs Cm update 81your 82checked out source. Automatic updates can interfere with 83any work-in-progress that you have. 84.Sh SSH DSA KEYS: 85The CVS repository machine is 86.Pa crater.dragonflybsd.org , 87and the 88.Dx 89developer machine is 90.Pa leaf.dragonflybsd.org . 91We create 92an account for you on both machines and install your public SSH 93key to give you access. 94.Pp 95Your 96.Pa crater 97account is set up for CVS repository only. It can 98only operate as a CVS slave and cannot be logged into. That is, 99.Pa crater.dragonflybsd.org 100is only used as part of 101.Nm cvs Fl d Ar ... 102operations. 103.Pp 104Your 105.Pa leaf 106account is a general developer account. Any 107.Dx 108developer can have a 109.Pa leaf 110account, whether a committer or not. 111It can be useful as a developer rendezvous, 112however. For example, people upload kernel cores to 113.Pa leaf 114so other 115developers can look at them. You log into your 116.Pa leaf 117account with: 118.Pp 119.Li ssh you@leaf.dragonflybsd.org 120.Pp 121The rules for account use are in 122.Pa leaf Ap s 123MOTD. 124It is very important that you never install a password or create a SSH 125key pair on 126.Pa leaf 127to use to access other machines. 128Because non-committers can have 129.Pa leaf 130accounts, since 131.Pa leaf 132is not considered 133a secure machine. 134.Sh TESTING COMMIT ACCESS 135There is a directory called 136.Pa /usr/src/test/test . 137To test your commit 138access, try making a modification and committing a file in this 139directory. 140.Pp 141.Bd -literal -offset indent 142cd /usr/src/test/test 143(edit something) 144cvs -d you@crater.dragonflybsd.org:/cvs commit file_you_edited 145.Ed 146.Sh COMMITTING REAL WORK 147Make modifications as needed. For example, edit files. If adding 148new files make CVS aware of them like this. Files can just be 149added locally, but directories have to run through 150.Pa crater . 151These 152operations do not actually affect the repository (except directories 153being added are mkdir'd in the repository). Instead they are 154stored in the checkout source's 155.Pa CVS/ 156subdirectory and then 157synchronized to the repository when you 158.Nm cvs Cm commit . 159.Pp 160.Bd -literal -offset indent 161cvs add filename 162cvs -d you@crater.dragonflybsd.org:/cvs add directory 163.Ed 164.Pp 165To commit to the repository, use: 166.Bd -literal -offset indent 167cvs -d you@crater.dragonflybsd.org:/cvs commit files_or_directories 168.Ed 169.Pp 170Do not set 171.Ev CVSROOT 172to 173.Pa you@crater.dragonflybsd.org:/cvs . 174The reason is that you want the default 175.Ev CVSROOT 176in your checked out 177sources to point at your local CVS repository, not at 178.Pa crater . 179This reduces instances where accidental commits or repository 180operations are made on 181.Pa crater . 182.Pp 183It is best to avoid 184.Nm cvs Cm update Ap ing 185directly from the repository. 186e.g. try to avoid doing 187.Nm cvs Fl d Ar ... Cm update 188directly from 189.Pa crater . 190Instead, use 191.Xr cvsup 1 192to resync your local copy of the repository 193and use 194.Nm cvs Cm update 195or 196.Nm cvs Fl d Ar /home/dcvs Cm update 197to update from 198your local copy of the repository. 199.Pp 200The idea here is to try to avoid having CVS set its 201.Pa CVS/Root 202file in any given checked out CVS directory to point at 203.Pa crater . 204You really want it to just point at your local copy of the CVS 205repository. 206.Pp 207Never do 208.Nm cvs Cm tag 209or 210.Cm rtag 211operations. Such operations can be 212very dangerous and only highly experienced CVS admins should 213do them. That's basically just two or three people (Matt and Joerg 214primarily). 215.Pp 216The best way to resynchronize your local CVS repository after 217making a commit is to cvsup again. 218.Sh DISCUSSING COMMITTABLE WORK BEFORE HAND 219Discussion prior to commit usually occurs on the kernel@, submit@, or bugs@ 220mailing lists. It depends on the work involved. Simple and obvious work, 221such as documentation edits or additions, don't really need a head's up. 222.Pp 223Simple and obvious bug fixes don't need a head's up, other than to 224say that you will (or just have) committed the fix, so you don't 225race other committers trying to do the same thing. Usually the 226developer most active in a discussion about a bug commits the 227fix, but it isn't considered a big deal. 228.Pp 229More complex issues are usually discussed on the lists first. 230Non-trivial but straight forward bug fixes usually go through 231a testing period, where you say something like: 232.Do 233Here is a patch 234to driver BLAH that fixes A, B, and C, please test it. If there 235are no objections I will commit it next Tuesday. 236.Dc 237(usually a week, 238or more depending on the complexity of the patch). 239.Pp 240New drivers or utilities are usually discussed. Committers will 241often commit new work 242.Em without 243hooking it into the buildworld or 244buildkernel infrastructure in order to be able to continue 245development on it in piecemeal without having to worry about it 246breaking buildworld or buildkernel, and then they hook it in as a 247last step after they've stabilized it. Examples of this include 248new versions of GCC, updates to vendor packages such as bind, 249sendmail, etc. 250.Sh DEVELOPER LOCKS 251Areas within the CVS repository are never explicitly locked. 252Often situations will arise where one developer commits work and 253another developer finds an issue with it that needs to be corrected. 254.Pp 255All committed work becomes community property. No developer has a 256.Sq lock 257on any part of the source tree. However, if a developer is 258actively working on a portion of the source tree and you find a bug 259or other issue, courtesy dictates that you post to kernel@ and/or 260email the developer. 261.Pp 262This means that, generally, if you do not see a commit to an area 263of the source tree in the last few weeks, it isn't considered active and 264you don't really need to confer with the developer that made the 265commit, though you should still post to the kernel@ mailing list 266and, of course, confer with developers when their expertise is 267needed. 268.Pp 269One exception to this rule is documentation. If any developer commits 270new work, the documentation guys have free reign to go in and 271correct 272.Xr mdoc 7 273errors. This is really a convenience as most developers 274are not 275.Xr mdoc 7 276gurus and it's a waste of time for the doc guys to post 277to kernel@ for all the little corrections they make. 278.Sh CONFLICTS 279On the occasion that a major code conflict occurs, for example if two 280people are doing major work in the same area of the source tree and forgot 281to collaborate with each other, the project leader will be responsible for 282resolving the conflict. Again, the repository is considered community 283property and it must be acceptable for any developer to be able to work on 284any area of the tree that he or she has an interest in. 285.Sh MAJOR ARCHITECTURAL CHANGES 286This is generally Matt Dillon's area of expertise. All major architectural 287changes must be discussed on the kernel@ mailing list and he retains 288veto power. 289.Pp 290This isn't usually an issue with any work. At best if something 291doesn't look right architecturally he'll chip in with adjustments to 292make it fit in. Nothing ever really gets vetoed. 293.Sh SEE ALSO 294.Xr cvs 1 , 295.Xr cvsup 1 , 296.Xr development 7 297