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