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