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 26, 2009
  36 .Dt COMMITTER 7
  37 .Os
  38 .Sh NAME
  39 .Nm committer
  40 .Nd instructions and rules for DragonFly committers
  41 .Sh SETTING UP GIT
  42 See
  43 .Xr development 7
  44 on how to pull a fresh copy of the
  45 .Dx
  46 .Xr git 1
  47 repository.
  48 .Pp
  49 Committers have to push to
  50 .Pa crater.dragonflybsd.org
  51 via
  52 .Xr ssh 1 .
  53 If the system is set up to pull from a
  54 .Dx
  55 mirror, a remote entry will have to be set up:
  56 .Bd -literal -offset indent
  57 git remote add crater \\
  58         ssh://crater.dragonflybsd.org/repository/git/dragonfly.git
  59 .Ed
  60 .Pp
  61 Your
  62 .Pa ~/.gitconfig
  63 should contain at least:
  64 .Bd -literal -offset indent
  65 [user]
  66         name = Your Name
  67         email = <login>@dragonflybsd.org
  68 .Ed
  69 .Pp
  70 Alternatively, see the
  71 .Va user.name
  72 and
  73 .Va user.email
  74 variables in
  75 .Xr git-config 1 .
  76 .Sh SSH DSA KEYS
  77 The git repository machine is
  78 .Pa crater.dragonflybsd.org ,
  79 and the
  80 .Dx
  81 developer machine is
  82 .Pa leaf.dragonflybsd.org .
  83 We create
  84 an account for you on both machines and install your public SSH
  85 key to give you access.
  86 .Pp
  87 Your
  88 .Pa crater
  89 account is set up for repository access only.
  90 It can only operate as a git slave and cannot be logged into.
  91 That is,
  92 .Pa crater.dragonflybsd.org
  93 is only used as part of
  94 .Nm git Cm push
  95 operations.
  96 .Pp
  97 Your
  98 .Pa leaf
  99 account is a general developer account.
 100 Any
 101 .Dx
 102 developer can have a
 103 .Pa leaf
 104 account, whether a committer or not.
 105 It can be useful as a developer rendezvous,
 106 however.
 107 For example, people upload kernel cores to
 108 .Pa leaf
 109 so other
 110 developers can look at them.
 111 You log into your
 112 .Pa leaf
 113 account with:
 114 .Bd -literal -offset indent
 115 ssh you@leaf.dragonflybsd.org
 116 .Ed
 117 .Pp
 118 The rules for account use are in
 119 .Pa leaf Ap s
 120 MOTD.
 121 It is very important that you never install a password or create a SSH
 122 key pair on
 123 .Pa leaf
 124 to use to access other machines.
 125 Because non-committers can have
 126 .Pa leaf
 127 accounts,
 128 .Pa leaf
 129 is not considered a secure machine.
 130 .Sh TESTING COMMIT ACCESS
 131 There is a directory called
 132 .Pa /usr/src/test/test .
 133 To test your commit
 134 access, try making a modification and committing a file in this
 135 directory.
 136 Try to push the commit to
 137 .Pa crater
 138 afterwards.
 139 .Bd -literal -offset indent
 140 cd /usr/src/test/test
 141 (edit something)
 142 git commit file_you_edited
 143 git push crater
 144 .Ed
 145 .Sh COMMITTING REAL WORK
 146 Make modifications as needed.
 147 For example, edit files.
 148 Files and directories can just be added locally.
 149 They are stored in your local copy of the repository and then
 150 synchronized with
 151 .Pa crater Ap s
 152 repository when you
 153 .Nm git Cm push .
 154 When adding new files make git aware of them like this:
 155 .Bd -literal -offset indent
 156 git add filename
 157 git commit filename
 158 .Ed
 159 .Pp
 160 To actually push your changes to the repository on
 161 .Pa crater ,
 162 use:
 163 .Bd -literal -offset indent
 164 git push crater
 165 .Ed
 166 .Pp
 167 To merge bug fixes to other branches (MFC), use
 168 .Nm git Cm cherry-pick :
 169 .Bd -literal -offset indent
 170 git checkout -b rel2_2 crater/DragonFly_RELEASE_2_2
 171 git cherry-pick <commit>
 172 git push crater rel2_2:DragonFly_RELEASE_2_2
 173 .Ed
 174 .Pp
 175 Do not set the default remote tag to
 176 .Pa origin .
 177 It is set to
 178 .Pa crater
 179 by default.
 180 This reduces instances where accidental commits or repository
 181 operations are made on the master repository.
 182 .Pp
 183 It is recommended to enable the MFC-detection commit hook, so that
 184 you are reminded of MFCing in case certain keywords are detected in
 185 the commit message. To do so, copy the hook into place:
 186 .Bd -literal -offset indent
 187 cp /usr/src/tools/commit-msg /usr/src/.git/hooks/commit-msg
 188 .Ed
 189 .Sh STRUCTURE OF COMMIT MESSAGES
 190 As many
 191 .Xr git 1
 192 tools display the first line of a commit message as a summary,
 193 structure your commit messages like this, if possible:
 194 .Bd -literal -offset indent
 195 One line summary of your change (less than 50 characters).
 196
 197 Maybe more text here describing your changes in detail (including
 198 issue tracker IDs etc).
 199 .Ed
 200 .Pp
 201 To customize the commit template for
 202 .Dx ,
 203 use:
 204 .Bd -literal -offset indent
 205 git config --add commit.template /usr/src/tools/gittemplate
 206 .Ed
 207 .Sh DISCUSSING COMMITTABLE WORK BEFOREHAND
 208 Discussion prior to committing usually occurs on the
 209 .Pa kernel@ ,
 210 .Pa submit@ ,
 211 or
 212 .Pa bugs@
 213 mailing lists and depends on the work involved.
 214 Simple and obvious work such as documentation edits or additions
 215 doesn't really need a heads up.
 216 .Pp
 217 Simple and obvious bug fixes don't need a heads up either, other than to
 218 say that you will (or just have) committed the fix, so you don't
 219 race other committers trying to do the same thing.
 220 Usually the developer most active in a discussion about a bug commits the
 221 fix, but it isn't considered a big deal.
 222 .Pp
 223 More complex issues are usually discussed on the lists first.
 224 Non-trivial but straight forward bug fixes usually go through
 225 a testing period, where you say something like:
 226 .Do
 227 Here is a patch
 228 to driver BLAH that fixes A, B, and C, please test it.
 229 If there are no objections I will commit it next Tuesday.
 230 .Dc
 231 (usually a week,
 232 or more depending on the complexity of the patch).
 233 .Pp
 234 New drivers or utilities are usually discussed.
 235 Committers will often commit new work
 236 .Em without
 237 hooking it into the buildworld or
 238 buildkernel infrastructure in order to be able to continue
 239 development on it in piecemeal without having to worry about it
 240 breaking buildworld or buildkernel, and then they hook it in as a
 241 last step after they've stabilized it.
 242 Examples of this include
 243 new versions of GCC, updates to vendor packages such as bind,
 244 sendmail, etc.
 245 .Sh SOURCE OWNERSHIP
 246 Areas within the repository do not
 247 .Dq belong
 248 to any committer.
 249 Often situations will arise where one developer commits work and
 250 another developer finds an issue with it that needs to be corrected.
 251 .Pp
 252 All committed work becomes community property.
 253 No developer has a
 254 .Dq lock
 255 on any part of the source tree.
 256 However, if a developer is
 257 actively working on a portion of the source tree and you find a bug
 258 or other issue, courtesy dictates that you post to
 259 .Pa kernel@
 260 and/or email the developer.
 261 .Pp
 262 This means that, generally, if you do not see a commit to an area
 263 of the source tree in the last few weeks, it isn't considered active and
 264 you don't really need to confer with the developer that made the
 265 commit, though you should still post to the
 266 .Pa kernel@
 267 mailing list and, of course, confer with developers when their expertise
 268 is needed.
 269 .Pp
 270 One exception to this rule is documentation.
 271 If any developer commits
 272 new work, the documentation guys have free reign to go in and correct
 273 .Xr mdoc 7
 274 errors.
 275 This is really a convenience as most developers are not
 276 .Xr mdoc 7
 277 gurus and it's a waste of time for the doc guys to post to
 278 .Pa kernel@
 279 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.
 285 Again, the repository is considered community
 286 property and it must be acceptable for any developer to be able to work on
 287 any area of the tree that he or she has an interest in.
 288 .Sh MAJOR ARCHITECTURAL CHANGES
 289 This is generally
 290 .An Matt Dillon Ap s
 291 area of expertise.
 292 All major architectural changes must be discussed on the
 293 .Pa kernel@
 294 mailing list and he retains veto power.
 295 .Pp
 296 This isn't usually an issue with any work.
 297 At best if something
 298 doesn't look right architecturally he'll chip in with adjustments to
 299 make it fit in.
 300 Nothing ever really gets vetoed.
 301 .Sh SEE ALSO
 302 .Xr git 1 Pq Pa pkgsrc/devel/scmgit ,
 303 .Xr development 7