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