share/man/man7/committer.7

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