Commit | Line | Data |
---|---|---|
413cd69c KH |
1 | Checklist (and a short version for the impatient): |
2 | ||
3 | Commits: | |
4 | ||
4dd55aec KH |
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 | |
413cd69c KH |
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 | |
4dd55aec KH |
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. | |
413cd69c KH |
19 | |
20 | Patch: | |
21 | ||
4dd55aec KH |
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. | |
413cd69c KH |
27 | body, unless you cannot teach your mailer to |
28 | leave the formatting of the patch alone. | |
4dd55aec | 29 | - Be careful doing cut & paste into your mailer, not to |
413cd69c | 30 | corrupt whitespaces. |
4dd55aec KH |
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 | |
413cd69c KH |
36 | make some other user interface change, the associated |
37 | documentation should be updated as well. | |
4dd55aec | 38 | - If your name is not writable in ASCII, make sure that |
413cd69c | 39 | you send off a message in the correct encoding. |
4dd55aec KH |
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. | |
413cd69c | 43 | |
413cd69c | 44 | |
4dd55aec | 45 | Long version: |
413cd69c | 46 | |
413cd69c | 47 | |
4dd55aec KH |
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: | |
413cd69c KH |
151 | |
152 | Developer's Certificate of Origin 1.1 | |
153 | ||
154 | By making a contribution to this project, I certify that: | |
155 | ||
4dd55aec KH |
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 | |
413cd69c | 159 | |
4dd55aec KH |
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 | |
413cd69c KH |
167 | |
168 | (c) The contribution was provided directly to me by some other | |
4dd55aec KH |
169 | person who certified (a), (b) or (c) and I have not |
170 | modified it. | |
413cd69c | 171 | |
4dd55aec KH |
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. | |
413cd69c | 178 | |
4dd55aec | 179 | then you just add a line saying |
413cd69c | 180 | |
4dd55aec | 181 | Signed-off-by: Random J Developer <random@developer.example.org> |
413cd69c | 182 | |
4dd55aec KH |
183 | This line can be automatically added by StGit by any command that |
184 | accepts the --sign option. | |
413cd69c | 185 | |
4dd55aec KH |
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). | |
413cd69c | 191 | |
4dd55aec KH |
192 | Also notice that a real name is used in the Signed-off-by: line. |
193 | Please don't hide your real name. | |
413cd69c | 194 | |
4dd55aec | 195 | Some people also put extra tags at the end. |
413cd69c | 196 | |
4dd55aec KH |
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. | |
413cd69c | 201 | |
413cd69c KH |
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 | |
4dd55aec | 226 | public repository: |
413cd69c | 227 | |
4dd55aec | 228 | $ git fetch http://homepage.ntlworld.com/cmarinas/stgit.git master:test-apply |
413cd69c KH |
229 | $ git checkout test-apply |
230 | $ git reset --hard | |
4dd55aec KH |
231 | $ stg init |
232 | $ stg import -M a.patch | |
413cd69c KH |
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 | ||
4dd55aec KH |
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. | |
413cd69c KH |
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! |