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.11 2008/05/02 02:05:06 swildner Exp $ 34.\" 35.Dd March 16, 2008 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.Bd -literal -offset indent 141cd /usr/src/test/test 142(edit something) 143cvs -d you@crater.dragonflybsd.org:/cvs commit file_you_edited 144.Ed 145.Sh COMMITTING REAL WORK 146Make modifications as needed. For example, edit files. If adding 147new files make CVS aware of them like this. Files can just be 148added locally, but directories have to run through 149.Pa crater . 150These 151operations do not actually affect the repository (except directories 152being added are mkdir'd in the repository). Instead they are 153stored in the checkout source's 154.Pa CVS/ 155subdirectory and then 156synchronized to the repository when you 157.Nm cvs Cm commit . 158.Bd -literal -offset indent 159cvs add filename 160cvs -d you@crater.dragonflybsd.org:/cvs add directory 161.Ed 162.Pp 163To commit to the repository, use: 164.Bd -literal -offset indent 165cvs -d you@crater.dragonflybsd.org:/cvs commit files_or_directories 166.Ed 167.Pp 168The recommended way for committing to a specific branch (to merge bug fixes, 169for example) is to 170.Nm cvs Cm checkout 171the branch in a different directory, modify there, and commit normally: 172.Bd -literal -offset indent 173cvs checkout -r DragonFly_RELEASE_1_12 src 174.Ed 175.Pp 176Do not set 177.Ev CVSROOT 178to 179.Pa you@crater.dragonflybsd.org:/cvs . 180The reason is that you want the default 181.Ev CVSROOT 182in your checked out 183sources to point at your local CVS repository, not at 184.Pa crater . 185This reduces instances where accidental commits or repository 186operations are made on 187.Pa crater . 188.Pp 189It is best to avoid 190.Nm cvs Cm update Ap ing 191directly from the repository. 192e.g. try to avoid doing 193.Nm cvs Fl d Ar ... Cm update 194directly from 195.Pa crater . 196Instead, use 197.Xr cvsup 1 198to resync your local copy of the repository 199and use 200.Nm cvs Cm update 201or 202.Nm cvs Fl d Ar /home/dcvs Cm update 203to update from 204your local copy of the repository. 205.Pp 206The idea here is to try to avoid having CVS set its 207.Pa CVS/Root 208file in any given checked out CVS directory to point at 209.Pa crater . 210You really want it to just point at your local copy of the CVS 211repository. 212.Pp 213Never do 214.Nm cvs Cm tag 215or 216.Cm rtag 217operations. Such operations can be 218very dangerous and only highly experienced CVS admins should 219do them. That's basically just two or three people (Matt and Joerg 220primarily). 221.Pp 222The best way to resynchronize your local CVS repository after 223making a commit is to cvsup again. 224.Sh DISCUSSING COMMITTABLE WORK BEFORE HAND 225Discussion prior to commit usually occurs on the kernel@, submit@, or bugs@ 226mailing lists. It depends on the work involved. Simple and obvious work, 227such as documentation edits or additions, don't really need a head's up. 228.Pp 229Simple and obvious bug fixes don't need a head's up, other than to 230say that you will (or just have) committed the fix, so you don't 231race other committers trying to do the same thing. Usually the 232developer most active in a discussion about a bug commits the 233fix, but it isn't considered a big deal. 234.Pp 235More complex issues are usually discussed on the lists first. 236Non-trivial but straight forward bug fixes usually go through 237a testing period, where you say something like: 238.Do 239Here is a patch 240to driver BLAH that fixes A, B, and C, please test it. If there 241are no objections I will commit it next Tuesday. 242.Dc 243(usually a week, 244or more depending on the complexity of the patch). 245.Pp 246New drivers or utilities are usually discussed. Committers will 247often commit new work 248.Em without 249hooking it into the buildworld or 250buildkernel infrastructure in order to be able to continue 251development on it in piecemeal without having to worry about it 252breaking buildworld or buildkernel, and then they hook it in as a 253last step after they've stabilized it. Examples of this include 254new versions of GCC, updates to vendor packages such as bind, 255sendmail, etc. 256.Sh DEVELOPER LOCKS 257Areas within the CVS repository are never explicitly locked. 258Often situations will arise where one developer commits work and 259another developer finds an issue with it that needs to be corrected. 260.Pp 261All committed work becomes community property. No developer has a 262.Sq lock 263on any part of the source tree. However, if a developer is 264actively working on a portion of the source tree and you find a bug 265or other issue, courtesy dictates that you post to kernel@ and/or 266email the developer. 267.Pp 268This means that, generally, if you do not see a commit to an area 269of the source tree in the last few weeks, it isn't considered active and 270you don't really need to confer with the developer that made the 271commit, though you should still post to the kernel@ mailing list 272and, of course, confer with developers when their expertise is 273needed. 274.Pp 275One exception to this rule is documentation. If any developer commits 276new work, the documentation guys have free reign to go in and 277correct 278.Xr mdoc 7 279errors. This is really a convenience as most developers 280are not 281.Xr mdoc 7 282gurus and it's a waste of time for the doc guys to post 283to kernel@ for all the little corrections they make. 284.Sh CONFLICTS 285On the occasion that a major code conflict occurs, for example if two 286people are doing major work in the same area of the source tree and forgot 287to collaborate with each other, the project leader will be responsible for 288resolving the conflict. Again, the repository is considered community 289property and it must be acceptable for any developer to be able to work on 290any area of the tree that he or she has an interest in. 291.Sh MAJOR ARCHITECTURAL CHANGES 292This is generally Matt Dillon's area of expertise. All major architectural 293changes must be discussed on the kernel@ mailing list and he retains 294veto power. 295.Pp 296This isn't usually an issue with any work. At best if something 297doesn't look right architecturally he'll chip in with adjustments to 298make it fit in. Nothing ever really gets vetoed. 299.Sh SEE ALSO 300.Xr cvs 1 , 301.Xr cvsup 1 , 302.Xr development 7 303