1 .\" Copyright (c) 2003,2004 The DragonFly Project. All rights reserved.
3 .\" This code is derived from software contributed to The DragonFly Project
4 .\" by Matthew Dillon <dillon@backplane.com>
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
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
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.
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
33 .\" $DragonFly: src/share/man/man7/committer.7,v 1.11 2008/05/02 02:05:06 swildner Exp $
40 .Nd instructions and rules for DragonFly committers
44 on how to pull a fresh copy of the
49 Committers have to push to
50 .Pa crater.dragonflybsd.org
53 If the system is set up to pull from a
55 mirror, a remote entry will have to be set up:
56 .Bd -literal -offset indent
57 git remote add crater \\
58 ssh://crater.dragonflybsd.org/repository/git/dragonfly.git
63 should contain at least:
64 .Bd -literal -offset indent
67 email = <login>@dragonflybsd.org
70 Alternatively, see the
77 The git repository machine is
78 .Pa crater.dragonflybsd.org ,
82 .Pa leaf.dragonflybsd.org .
84 an account for you on both machines and install your public SSH
85 key to give you access.
89 account is set up for repository access only.
90 It can only operate as a git slave and cannot be logged into.
92 .Pa crater.dragonflybsd.org
93 is only used as part of
99 account is a general developer account.
104 account, whether a committer or not.
105 It can be useful as a developer rendezvous,
107 For example, people upload kernel cores to
110 developers can look at them.
114 .Bd -literal -offset indent
115 ssh you@leaf.dragonflybsd.org
118 The rules for account use are in
121 It is very important that you never install a password or create a SSH
124 to use to access other machines.
125 Because non-committers can have
129 is not considered a secure machine.
130 .Sh TESTING COMMIT ACCESS
131 There is a directory called
132 .Pa /usr/src/test/test .
134 access, try making a modification and committing a file in this
136 Try to push the commit to
139 .Bd -literal -offset indent
140 cd /usr/src/test/test
142 git commit file_you_edited
145 .Sh COMMITTING REAL WORK
146 Make modifications as needed.
147 For example, edit files.
148 Files and directories can just be added locally.
149 They are stored in your local copy of the repository and then
154 When adding new files make git aware of them like this:
155 .Bd -literal -offset indent
160 To actually push your changes to the repository on
163 .Bd -literal -offset indent
167 To merge bug fixes to other branches (MFC), use
168 .Nm git Cm cherry-pick :
169 .Bd -literal -offset indent
170 git checkout -b rel2_2 crater/DragonFly_RELEASE_2_2
171 git cherry-pick <commit>
172 git push crater rel2_2:DragonFly_RELEASE_2_2
175 Do not set the default remote tag to
180 This reduces instances where accidental commits or repository
181 operations are made on the master repository.
182 .Sh STRUCTURE OF COMMIT MESSAGES
185 tools display the first line of a commit message as a summary,
186 structure your commit messages like this, if possible:
187 .Bd -literal -offset indent
188 One line summary of your change (less than 50 characters).
190 Maybe more text here describing your changes in detail (including
191 issue tracker IDs etc).
194 To customize the commit template for
197 .Bd -literal -offset indent
198 git config --add commit.template /usr/src/tools/gittemplate
200 .Sh DISCUSSING COMMITTABLE WORK BEFOREHAND
201 Discussion prior to committing usually occurs on the
206 mailing lists and depends on the work involved.
207 Simple and obvious work such as documentation edits or additions
208 doesn't really need a heads up.
210 Simple and obvious bug fixes don't need a heads up either, other than to
211 say that you will (or just have) committed the fix, so you don't
212 race other committers trying to do the same thing.
213 Usually the developer most active in a discussion about a bug commits the
214 fix, but it isn't considered a big deal.
216 More complex issues are usually discussed on the lists first.
217 Non-trivial but straight forward bug fixes usually go through
218 a testing period, where you say something like:
221 to driver BLAH that fixes A, B, and C, please test it.
222 If there are no objections I will commit it next Tuesday.
225 or more depending on the complexity of the patch).
227 New drivers or utilities are usually discussed.
228 Committers will often commit new work
230 hooking it into the buildworld or
231 buildkernel infrastructure in order to be able to continue
232 development on it in piecemeal without having to worry about it
233 breaking buildworld or buildkernel, and then they hook it in as a
234 last step after they've stabilized it.
235 Examples of this include
236 new versions of GCC, updates to vendor packages such as bind,
239 Areas within the repository do not
242 Often situations will arise where one developer commits work and
243 another developer finds an issue with it that needs to be corrected.
245 All committed work becomes community property.
248 on any part of the source tree.
249 However, if a developer is
250 actively working on a portion of the source tree and you find a bug
251 or other issue, courtesy dictates that you post to
253 and/or email the developer.
255 This means that, generally, if you do not see a commit to an area
256 of the source tree in the last few weeks, it isn't considered active and
257 you don't really need to confer with the developer that made the
258 commit, though you should still post to the
260 mailing list and, of course, confer with developers when their expertise
263 One exception to this rule is documentation.
264 If any developer commits
265 new work, the documentation guys have free reign to go in and correct
268 This is really a convenience as most developers are not
270 gurus and it's a waste of time for the doc guys to post to
272 for all the little corrections they make.
274 On the occasion that a major code conflict occurs, for example if two
275 people are doing major work in the same area of the source tree and forgot
276 to collaborate with each other, the project leader will be responsible for
277 resolving the conflict.
278 Again, the repository is considered community
279 property and it must be acceptable for any developer to be able to work on
280 any area of the tree that he or she has an interest in.
281 .Sh MAJOR ARCHITECTURAL CHANGES
285 All major architectural changes must be discussed on the
287 mailing list and he retains veto power.
289 This isn't usually an issue with any work.
291 doesn't look right architecturally he'll chip in with adjustments to
293 Nothing ever really gets vetoed.
295 .Xr git 1 Pq Pa pkgsrc/devel/scmgit ,