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