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