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