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