chiark / gitweb /
Remove the assert in CommitData.parse() function
[stgit] / Documentation / SubmittingPatches
1 Checklist (and a short version for the impatient):
2
3         Commits:
4
5         - Make commits of logical units.
6         - Check for unnecessary whitespace with "git diff --check"
7           before committing.
8         - Do not check in commented out code or unneeded files.
9         - Provide a meaningful commit message.
10         - The first line of the commit message should be a short
11           description and should skip the full stop.
12         - If you want your work included in StGit, add a
13           "Signed-off-by: Your Name <you@example.com>" line to the
14           commit message (or just use the option "-s" when
15           committing) to confirm that you agree to the Developer's
16           Certificate of Origin.
17         - Make sure that you have tests for the bug you are fixing.
18         - Make sure that the test suite passes after your commit.
19
20         Patch:
21
22         - Preferably use "stg mail" to send patches. The first time,
23           it's a good idea to try to mail the patches to yourself to
24           see that everything works.
25         - Do not PGP sign your patch.
26         - Do not attach your patch, but read in the mail.
27           body, unless you cannot teach your mailer to
28           leave the formatting of the patch alone.
29         - Be careful doing cut & paste into your mailer, not to
30           corrupt whitespaces.
31         - Provide additional information (which is unsuitable for the
32           commit message) between the "---" and the diffstat. (The -E
33           option to stg mail lets you edit the message before you send
34           it out.)
35         - If you change, add, or remove a command line option or
36           make some other user interface change, the associated
37           documentation should be updated as well.
38         - If your name is not writable in ASCII, make sure that
39           you send off a message in the correct encoding.
40         - Send the patch to the list (git@vger.kernel.org) and the
41           maintainer (catalin.marinas@gmail.com) if (and only if) the
42           patch is ready for inclusion.
43
44
45 Long version:
46
47
48 1. Make separate commits for logically separate changes.
49
50    Unless your patch is really trivial, you should not be sending out
51    a patch that was generated between your working tree and your
52    commit head. Instead, always make a commit with complete commit
53    message and generate a series of patches from your repository. It
54    is a good discipline.
55
56    Describe the technical detail of the change(s).
57
58    If your description starts to get too long, that's a sign that you
59    probably need to split up your commit to finer grained pieces.
60
61    Oh, another thing. I am picky about whitespaces. Please run git
62    diff --check on your changes before you commit.
63
64
65 2. Generate your patch using Git tools out of your commits.
66
67    Git based diff tools (Git, Cogito, and StGit included) generate
68    unidiff which is the preferred format.
69
70    You do not have to be afraid to use -M option to "git diff" and
71    friends, if your patch involves file renames. The receiving end can
72    handle them just fine.
73
74    Please make sure your patch does not include any extra files which
75    do not belong in a patch submission. Make sure to review your patch
76    after generating it, to ensure accuracy. Before sending out, please
77    make sure it cleanly applies to the "master" branch head. If you
78    are preparing a work based on some other branch, that is fine, but
79    please mark it as such.
80
81
82 3. Sending your patches.
83
84    StGit patches should be sent to the Git mailing list
85    (git@vger.kernel.org), and preferably CCed to the StGit maintainer
86    (catalin.marinas@gmail.com). The recipients need to be able to read
87    and comment on the changes you are submitting. It is important for
88    a developer to be able to "quote" your changes, using standard
89    e-mail tools, so that they may comment on specific portions of your
90    code. For this reason, all patches should be submitted "inline".
91    WARNING: Be wary of your MUAs word-wrap corrupting your patch. Do
92    not cut-n-paste your patch; you can lose tabs that way if you are
93    not careful.
94
95    It is a common convention to prefix your subject line with [StGit
96    PATCH]. This lets people easily distinguish patches to StGit from
97    other e-mail discussions and patches meant for Git itself. Use of
98    additional markers after PATCH and the closing bracket to mark the
99    nature of the patch is also encouraged. E.g. [PATCH/RFC] is often
100    used when the patch is not ready to be applied but it is for
101    discussion, [PATCH v2], [PATCH v3] etc. are often seen when you are
102    sending an update to what you have previously sent.
103
104    "stg mail" command follows the best current practice to format the
105    body of an e-mail message. At the beginning of the patch should
106    come your commit message, ending with the Signed-off-by: lines, and
107    a line that consists of three dashes, followed by the diffstat
108    information and the patch itself. If you are forwarding a patch
109    from somebody else, optionally, at the beginning of the e-mail
110    message just before the commit message starts, you can put a
111    "From:" line to name that person.
112
113    You often want to add additional explanation about the patch, other
114    than the commit message itself. Place such "cover letter" material
115    between the three dash lines and the diffstat. If you have comments
116    about a whole series of patches, you can include them in a separate
117    cover mail message (the -e option to stg mail).
118
119    Do not attach the patch as a MIME attachment, compressed or not. Do
120    not let your e-mail client send quoted-printable. Do not let your
121    e-mail client send format=flowed which would destroy whitespaces in
122    your patches. Many popular e-mail applications will not always
123    transmit a MIME attachment as plain text, making it impossible to
124    comment on your code. A MIME attachment also takes a bit more time
125    to process. This does not decrease the likelihood of your
126    MIME-attached change being accepted, but it makes it more likely
127    that it will be postponed.
128
129    Exception: If your mailer is mangling patches then someone may ask
130    you to re-send them using MIME, that is OK.
131
132    Do not PGP sign your patch, at least for now. Most likely, your
133    maintainer or other people on the list would not have your PGP key
134    and would not bother obtaining it anyway. Your patch is not judged
135    by who you are; a good patch from an unknown origin has a far
136    better chance of being accepted than a patch from a known,
137    respected origin that is done poorly or does incorrect things.
138
139
140 4. Sign your work
141
142    To improve tracking of who did what, we've borrowed the "sign-off"
143    procedure from the Git and Linux kernel projects on patches that
144    are being emailed around. Although StGit is a lot smaller project
145    it is a good discipline to follow it.
146
147    The sign-off is a simple line at the end of the explanation for the
148    patch, which certifies that you wrote it or otherwise have the
149    right to pass it on as a open-source patch. The rules are pretty
150    simple: if you can certify the below:
151
152         Developer's Certificate of Origin 1.1
153
154         By making a contribution to this project, I certify that:
155
156         (a) The contribution was created in whole or in part by me and
157             I have the right to submit it under the open source
158             license indicated in the file; or
159
160         (b) The contribution is based upon previous work that, to the
161             best of my knowledge, is covered under an appropriate open
162             source license and I have the right under that license to
163             submit that work with modifications, whether created in
164             whole or in part by me, under the same open source license
165             (unless I am permitted to submit under a different
166             license), as indicated in the file; or
167
168         (c) The contribution was provided directly to me by some other
169             person who certified (a), (b) or (c) and I have not
170             modified it.
171
172         (d) I understand and agree that this project and the
173             contribution are public and that a record of the
174             contribution (including all personal information I submit
175             with it, including my sign-off) is maintained indefinitely
176             and may be redistributed consistent with this project or
177             the open source license(s) involved.
178
179    then you just add a line saying
180
181        Signed-off-by: Random J Developer <random@developer.example.org>
182
183    This line can be automatically added by StGit by any command that
184    accepts the --sign option.
185
186    Notice that you can place your own Signed-off-by: line when
187    forwarding somebody else's patch with the above rules for D-C-O.
188    Indeed you are encouraged to do so. Do not forget to place an
189    in-body "From: " line at the beginning to properly attribute the
190    change to its true author (see (2) above).
191
192    Also notice that a real name is used in the Signed-off-by: line.
193    Please don't hide your real name.
194
195    Some people also put extra tags at the end.
196
197    "Acked-by:" says that the patch was reviewed by a person who is
198    more familiar with the issues and the area the patch attempts to
199    modify. "Tested-by:" says the patch was tested by the person and
200    found to have the desired effect.
201
202
203 ------------------------------------------------
204 MUA specific hints
205
206 Some of patches I receive or pick up from the list share common
207 patterns of breakage.  Please make sure your MUA is set up
208 properly not to corrupt whitespaces.  Here are two common ones
209 I have seen:
210
211 * Empty context lines that do not have _any_ whitespace.
212
213 * Non empty context lines that have one extra whitespace at the
214   beginning.
215
216 One test you could do yourself if your MUA is set up correctly is:
217
218 * Send the patch to yourself, exactly the way you would, except
219   To: and Cc: lines, which would not contain the list and
220   maintainer address.
221
222 * Save that patch to a file in UNIX mailbox format.  Call it say
223   a.patch.
224
225 * Try to apply to the tip of the "master" branch from the
226   public repository:
227
228     $ git fetch http://homepage.ntlworld.com/cmarinas/stgit.git master:test-apply
229     $ git checkout test-apply
230     $ git reset --hard
231     $ stg init
232     $ stg import -M a.patch
233
234 If it does not apply correctly, there can be various reasons.
235
236 * Your patch itself does not apply cleanly.  That is _bad_ but
237   does not have much to do with your MUA.  Please rebase the
238   patch appropriately.
239
240 * Your MUA corrupted your patch; "stg import" would complain that
241   the patch does not apply.
242
243 * Check the imported patch with e.g. "stg show". If it isn't exactly
244   what you would want to see in the commit log message, it is very
245   likely that the maintainer would end up hand editing the log
246   message when he applies your patch. Things like "Hi, this is my
247   first patch.\n", if you really want to put in the patch e-mail,
248   should come after the three-dash line that signals the end of the
249   commit message.
250
251
252 Pine
253 ----
254
255 (Johannes Schindelin)
256
257 I don't know how many people still use pine, but for those poor
258 souls it may be good to mention that the quell-flowed-text is
259 needed for recent versions.
260
261 ... the "no-strip-whitespace-before-send" option, too. AFAIK it
262 was introduced in 4.60.
263
264 (Linus Torvalds)
265
266 And 4.58 needs at least this.
267
268 ---
269 diff-tree 8326dd8350be64ac7fc805f6563a1d61ad10d32c (from e886a61f76edf5410573e92e38ce22974f9c40f1)
270 Author: Linus Torvalds <torvalds@g5.osdl.org>
271 Date:   Mon Aug 15 17:23:51 2005 -0700
272
273     Fix pine whitespace-corruption bug
274
275     There's no excuse for unconditionally removing whitespace from
276     the pico buffers on close.
277
278 diff --git a/pico/pico.c b/pico/pico.c
279 --- a/pico/pico.c
280 +++ b/pico/pico.c
281 @@ -219,7 +219,9 @@ PICO *pm;
282             switch(pico_all_done){      /* prepare for/handle final events */
283               case COMP_EXIT :          /* already confirmed */
284                 packheader();
285 +#if 0
286                 stripwhitespace();
287 +#endif
288                 c |= COMP_EXIT;
289                 break;
290
291
292 (Daniel Barkalow)
293
294 > A patch to SubmittingPatches, MUA specific help section for
295 > users of Pine 4.63 would be very much appreciated.
296
297 Ah, it looks like a recent version changed the default behavior to do the
298 right thing, and inverted the sense of the configuration option. (Either
299 that or Gentoo did it.) So you need to set the
300 "no-strip-whitespace-before-send" option, unless the option you have is
301 "strip-whitespace-before-send", in which case you should avoid checking
302 it.
303
304
305 Thunderbird
306 -----------
307
308 (A Large Angry SCM)
309
310 Here are some hints on how to successfully submit patches inline using
311 Thunderbird.
312
313 This recipe appears to work with the current [*1*] Thunderbird from Suse.
314
315 The following Thunderbird extensions are needed:
316         AboutConfig 0.5
317                 http://aboutconfig.mozdev.org/
318         External Editor 0.7.2
319                 http://globs.org/articles.php?lng=en&pg=8
320
321 1) Prepare the patch as a text file using your method of choice.
322
323 2) Before opening a compose window, use Edit->Account Settings to
324 uncheck the "Compose messages in HTML format" setting in the
325 "Composition & Addressing" panel of the account to be used to send the
326 patch. [*2*]
327
328 3) In the main Thunderbird window, _before_ you open the compose window
329 for the patch, use Tools->about:config to set the following to the
330 indicated values:
331         mailnews.send_plaintext_flowed  => false
332         mailnews.wraplength             => 0
333
334 4) Open a compose window and click the external editor icon.
335
336 5) In the external editor window, read in the patch file and exit the
337 editor normally.
338
339 6) Back in the compose window: Add whatever other text you wish to the
340 message, complete the addressing and subject fields, and press send.
341
342 7) Optionally, undo the about:config/account settings changes made in
343 steps 2 & 3.
344
345
346 [Footnotes]
347 *1* Version 1.0 (20041207) from the MozillaThunderbird-1.0-5 rpm of Suse
348 9.3 professional updates.
349
350 *2* It may be possible to do this with about:config and the following
351 settings but I haven't tried, yet.
352         mail.html_compose                       => false
353         mail.identity.default.compose_html      => false
354         mail.identity.id?.compose_html          => false
355
356 (Lukas Sandström)
357
358 There is a script in contrib/thunderbird-patch-inline which can help
359 you include patches with Thunderbird in an easy way. To use it, do the
360 steps above and then use the script as the external editor.
361
362 Gnus
363 ----
364
365 '|' in the *Summary* buffer can be used to pipe the current
366 message to an external program, and this is a handy way to drive
367 "git am".  However, if the message is MIME encoded, what is
368 piped into the program is the representation you see in your
369 *Article* buffer after unwrapping MIME.  This is often not what
370 you would want for two reasons.  It tends to screw up non ASCII
371 characters (most notably in people's names), and also
372 whitespaces (fatal in patches).  Running 'C-u g' to display the
373 message in raw form before using '|' to run the pipe can work
374 this problem around.
375
376
377 KMail
378 -----
379
380 This should help you to submit patches inline using KMail.
381
382 1) Prepare the patch as a text file.
383
384 2) Click on New Mail.
385
386 3) Go under "Options" in the Composer window and be sure that
387 "Word wrap" is not set.
388
389 4) Use Message -> Insert file... and insert the patch.
390
391 5) Back in the compose window: add whatever other text you wish to the
392 message, complete the addressing and subject fields, and press send.
393
394
395 Gmail
396 -----
397
398 Submitting properly formatted patches via Gmail is simple now that
399 IMAP support is available. First, edit your ~/.gitconfig to specify your
400 account settings:
401
402 [imap]
403         folder = "[Gmail]/Drafts"
404         host = imaps://imap.gmail.com
405         user = user@gmail.com
406         pass = p4ssw0rd
407         port = 993
408         sslverify = false
409
410 Next, ensure that your Gmail settings are correct. In "Settings" the
411 "Use Unicode (UTF-8) encoding for outgoing messages" should be checked.
412
413 Once your commits are ready to send to the mailing list, run the following
414 command to send the patch emails to your Gmail Drafts folder.
415
416         $ git format-patch -M --stdout origin/master | git imap-send
417
418 Go to your Gmail account, open the Drafts folder, find the patch email, fill
419 in the To: and CC: fields and send away!