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