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