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