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 December 3, 2008 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 154See 155.Xr development 7 156how to commit to a specific branch (to merge bug fixes, for example). 157.Pp 158Do not set the default remote tag to 159.Pa origin . 160It is set to 161.Pa crater 162by default. 163This reduces instances where accidental commits or repository 164operations are made on the master repository. 165.Sh STRUCTURE OF COMMIT MESSAGES 166As many 167.Xr git 1 168tools display the first line of a commit message as a summary, 169structure your commit messages like this, if possible: 170.Bd -literal -offset indent 171One line summary of your change. 172 173Maybe more text here describing your changes in detail (including 174issue tracker id's etc). 175.Ed 176.Sh DISCUSSING COMMITTABLE WORK BEFOREHAND 177Discussion prior to committing usually occurs on the 178.Pa kernel@ , 179.Pa submit@ , 180or 181.Pa bugs@ 182mailing lists and depends on the work involved. 183Simple and obvious work such as documentation edits or additions, 184doesn't really need a heads up. 185.Pp 186Simple and obvious bug fixes don't need a heads up either, other than to 187say that you will (or just have) committed the fix, so you don't 188race other committers trying to do the same thing. 189Usually the developer most active in a discussion about a bug commits the 190fix, but it isn't considered a big deal. 191.Pp 192More complex issues are usually discussed on the lists first. 193Non-trivial but straight forward bug fixes usually go through 194a testing period, where you say something like: 195.Do 196Here is a patch 197to driver BLAH that fixes A, B, and C, please test it. 198If there are no objections I will commit it next Tuesday. 199.Dc 200(usually a week, 201or more depending on the complexity of the patch). 202.Pp 203New drivers or utilities are usually discussed. 204Committers will often commit new work 205.Em without 206hooking it into the buildworld or 207buildkernel infrastructure in order to be able to continue 208development on it in piecemeal without having to worry about it 209breaking buildworld or buildkernel, and then they hook it in as a 210last step after they've stabilized it. 211Examples of this include 212new versions of GCC, updates to vendor packages such as bind, 213sendmail, etc. 214.Sh SOURCE OWNERSHIP 215Areas within the repository do not 216.Dq belong 217to any committer. 218Often situations will arise where one developer commits work and 219another developer finds an issue with it that needs to be corrected. 220.Pp 221All committed work becomes community property. 222No developer has a 223.Dq lock 224on any part of the source tree. 225However, if a developer is 226actively working on a portion of the source tree and you find a bug 227or other issue, courtesy dictates that you post to 228.Pa kernel@ 229and/or email the developer. 230.Pp 231This means that, generally, if you do not see a commit to an area 232of the source tree in the last few weeks, it isn't considered active and 233you don't really need to confer with the developer that made the 234commit, though you should still post to the 235.Pa kernel@ 236mailing list and, of course, confer with developers when their expertise 237is needed. 238.Pp 239One exception to this rule is documentation. 240If any developer commits 241new work, the documentation guys have free reign to go in and correct 242.Xr mdoc 7 243errors. 244This is really a convenience as most developers are not 245.Xr mdoc 7 246gurus and it's a waste of time for the doc guys to post to 247.Pa kernel@ 248for all the little corrections they make. 249.Sh CONFLICTS 250On the occasion that a major code conflict occurs, for example if two 251people are doing major work in the same area of the source tree and forgot 252to collaborate with each other, the project leader will be responsible for 253resolving the conflict. 254Again, the repository is considered community 255property and it must be acceptable for any developer to be able to work on 256any area of the tree that he or she has an interest in. 257.Sh MAJOR ARCHITECTURAL CHANGES 258This is generally 259.An Matt Dillon Ap s 260area of expertise. 261All major architectural changes must be discussed on the 262.Pa kernel@ 263mailing list and he retains veto power. 264.Pp 265This isn't usually an issue with any work. 266At best if something 267doesn't look right architecturally he'll chip in with adjustments to 268make it fit in. 269Nothing ever really gets vetoed. 270.Sh SEE ALSO 271.Xr git 1 Pq Pa pkgsrc/devel/scmgit , 272.Xr development 7 273