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