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