]>
Commit | Line | Data |
---|---|---|
049e64aa | 1 | Submitting Patches |
2 | ================== | |
3 | ||
4 | == Guidelines | |
5 | ||
adcc42e6 JH |
6 | Here are some guidelines for people who want to contribute their code |
7 | to this software. | |
31408251 | 8 | |
049e64aa | 9 | [[base-branch]] |
10 | === Decide what to base your work on. | |
d0c26f0f RR |
11 | |
12 | In general, always base your work on the oldest branch that your | |
13 | change is relevant to. | |
14 | ||
049e64aa | 15 | * A bugfix should be based on `maint` in general. If the bug is not |
16 | present in `maint`, base it on `master`. For a bug that's not yet | |
17 | in `master`, find the topic that introduces the regression, and | |
18 | base your work on the tip of the topic. | |
d0c26f0f | 19 | |
049e64aa | 20 | * A new feature should be based on `master` in general. If the new |
21 | feature depends on a topic that is in `pu`, but not in `master`, | |
22 | base your work on the tip of that topic. | |
d0c26f0f | 23 | |
049e64aa | 24 | * Corrections and enhancements to a topic not yet in `master` should |
25 | be based on the tip of that topic. If the topic has not been merged | |
26 | to `next`, it's alright to add a note to squash minor corrections | |
27 | into the series. | |
d0c26f0f | 28 | |
049e64aa | 29 | * In the exceptional case that a new feature depends on several topics |
30 | not in `master`, start working on `next` or `pu` privately and send | |
31 | out patches for discussion. Before the final merge, you may have to | |
32 | wait until some of the dependent topics graduate to `master`, and | |
33 | rebase your work. | |
d0c26f0f | 34 | |
049e64aa | 35 | * Some parts of the system have dedicated maintainers with their own |
36 | repositories (see the section "Subsystems" below). Changes to | |
37 | these parts should be based on their trees. | |
e6da8ee8 | 38 | |
049e64aa | 39 | To find the tip of a topic branch, run `git log --first-parent |
40 | master..pu` and look for the merge commit. The second parent of this | |
d0c26f0f | 41 | commit is the tip of the topic branch. |
31408251 | 42 | |
049e64aa | 43 | [[separate-commits]] |
44 | === Make separate commits for logically separate changes. | |
31408251 JH |
45 | |
46 | Unless your patch is really trivial, you should not be sending | |
47 | out a patch that was generated between your working tree and | |
48 | your commit head. Instead, always make a commit with complete | |
49 | commit message and generate a series of patches from your | |
50 | repository. It is a good discipline. | |
51 | ||
d0f7dcbf JH |
52 | Give an explanation for the change(s) that is detailed enough so |
53 | that people can judge if it is good thing to do, without reading | |
54 | the actual patch text to determine how well the code does what | |
55 | the explanation promises to do. | |
31408251 | 56 | |
45d2b286 | 57 | If your description starts to get too long, that's a sign that you |
31408251 | 58 | probably need to split up your commit to finer grained pieces. |
47afed5d SV |
59 | That being said, patches which plainly describe the things that |
60 | help reviewers check the patch, and future maintainers understand | |
01e60a9a | 61 | the code, are the most beautiful patches. Descriptions that summarize |
47afed5d SV |
62 | the point in the subject well, and describe the motivation for the |
63 | change, the approach taken by the change, and if relevant how this | |
d0f7dcbf JH |
64 | differs substantially from the prior version, are all good things |
65 | to have. | |
31408251 | 66 | |
54cc5d29 | 67 | Make sure that you have tests for the bug you are fixing. See |
049e64aa | 68 | `t/README` for guidance. |
7d5bf87b | 69 | |
049e64aa | 70 | [[tests]] |
7d5bf87b | 71 | When adding a new feature, make sure that you have new tests to show |
0e5d028a LS |
72 | the feature triggers the new behavior when it should, and to show the |
73 | feature does not trigger when it shouldn't. After any code change, make | |
74 | sure that the entire test suite passes. | |
75 | ||
76 | If you have an account at GitHub (and you can get one for free to work | |
77 | on open source projects), you can use their Travis CI integration to | |
78 | test your changes on Linux, Mac (and hopefully soon Windows). See | |
79 | GitHub-Travis CI hints section for details. | |
80 | ||
81 | Do not forget to update the documentation to describe the updated | |
82 | behavior and make sure that the resulting documentation set formats | |
83 | well. It is currently a liberal mixture of US and UK English norms for | |
84 | spelling and grammar, which is somewhat unfortunate. A huge patch that | |
85 | touches the files all over the place only to correct the inconsistency | |
86 | is not welcome, though. Potential clashes with other changes that can | |
87 | result from such a patch are not worth it. We prefer to gradually | |
88 | reconcile the inconsistencies in favor of US English, with small and | |
89 | easily digestible patches, as a side effect of doing some other real | |
90 | work in the vicinity (e.g. rewriting a paragraph for clarity, while | |
91 | turning en_UK spelling to en_US). Obvious typographical fixes are much | |
92 | more welcomed ("teh -> "the"), preferably submitted as independent | |
93 | patches separate from other documentation changes. | |
42e0fae9 | 94 | |
049e64aa | 95 | [[whitespace-check]] |
42e0fae9 | 96 | Oh, another thing. We are picky about whitespaces. Make sure your |
45d2b286 | 97 | changes do not trigger errors with the sample pre-commit hook shipped |
049e64aa | 98 | in `templates/hooks--pre-commit`. To help ensure this does not happen, |
99 | run `git diff --check` on your changes before you commit. | |
31408251 | 100 | |
049e64aa | 101 | [[describe-changes]] |
102 | === Describe your changes well. | |
7d5bf87b JH |
103 | |
104 | The first line of the commit message should be a short description (50 | |
049e64aa | 105 | characters is the soft limit, see DISCUSSION in linkgit:git-commit[1]), |
106 | and should skip the full stop. It is also conventional in most cases to | |
7d5bf87b JH |
107 | prefix the first line with "area: " where the area is a filename or |
108 | identifier for the general area of the code being modified, e.g. | |
109 | ||
049e64aa | 110 | * doc: clarify distinction between sign-off and pgp-signing |
111 | * githooks.txt: improve the intro section | |
7d5bf87b | 112 | |
049e64aa | 113 | If in doubt which identifier to use, run `git log --no-merges` on the |
7d5bf87b JH |
114 | files you are modifying to see the current conventions. |
115 | ||
049e64aa | 116 | [[summary-section]] |
2ee00567 ÆAB |
117 | It's customary to start the remainder of the first line after "area: " |
118 | with a lower-case letter. E.g. "doc: clarify...", not "doc: | |
119 | Clarify...", or "githooks.txt: improve...", not "githooks.txt: | |
120 | Improve...". | |
121 | ||
049e64aa | 122 | [[meaningful-message]] |
7d5bf87b JH |
123 | The body should provide a meaningful commit message, which: |
124 | ||
049e64aa | 125 | . explains the problem the change tries to solve, i.e. what is wrong |
126 | with the current code without the change. | |
7d5bf87b | 127 | |
049e64aa | 128 | . justifies the way the change solves the problem, i.e. why the |
129 | result with the change is better. | |
7d5bf87b | 130 | |
049e64aa | 131 | . alternate solutions considered but discarded, if any. |
7d5bf87b | 132 | |
049e64aa | 133 | [[imperative-mood]] |
7d5bf87b JH |
134 | Describe your changes in imperative mood, e.g. "make xyzzy do frotz" |
135 | instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy | |
136 | to do frotz", as if you are giving orders to the codebase to change | |
01e60a9a | 137 | its behavior. Try to make sure your explanation can be understood |
7d5bf87b JH |
138 | without external resources. Instead of giving a URL to a mailing list |
139 | archive, summarize the relevant points of the discussion. | |
140 | ||
049e64aa | 141 | [[commit-reference]] |
175d38ca | 142 | If you want to reference a previous commit in the history of a stable |
4369523b BB |
143 | branch, use the format "abbreviated sha1 (subject, date)", |
144 | with the subject enclosed in a pair of double-quotes, like this: | |
145 | ||
049e64aa | 146 | .... |
147 | Commit f86a374 ("pack-bitmap.c: fix a memleak", 2015-03-30) | |
148 | noticed that ... | |
149 | .... | |
4369523b BB |
150 | |
151 | The "Copy commit summary" command of gitk can be used to obtain this | |
049e64aa | 152 | format, or this invocation of `git show`: |
175d38ca | 153 | |
049e64aa | 154 | .... |
155 | git show -s --date=short --pretty='format:%h ("%s", %ad)' <commit> | |
156 | .... | |
7d5bf87b | 157 | |
049e64aa | 158 | [[git-tools]] |
159 | === Generate your patch using Git tools out of your commits. | |
45d2b286 | 160 | |
2de9b711 | 161 | Git based diff tools generate unidiff which is the preferred format. |
45d2b286 | 162 | |
049e64aa | 163 | You do not have to be afraid to use `-M` option to `git diff` or |
164 | `git format-patch`, if your patch involves file renames. The | |
31408251 JH |
165 | receiving end can handle them just fine. |
166 | ||
049e64aa | 167 | [[review-patch]] |
7d5bf87b JH |
168 | Please make sure your patch does not add commented out debugging code, |
169 | or include any extra files which do not relate to what your patch | |
170 | is trying to achieve. Make sure to review | |
31408251 | 171 | your patch after generating it, to ensure accuracy. Before |
049e64aa | 172 | sending out, please make sure it cleanly applies to the `master` |
45d2b286 JH |
173 | branch head. If you are preparing a work based on "next" branch, |
174 | that is fine, but please mark it as such. | |
31408251 | 175 | |
049e64aa | 176 | [[send-patches]] |
177 | === Sending your patches. | |
31408251 | 178 | |
b25c4699 JH |
179 | Learn to use format-patch and send-email if possible. These commands |
180 | are optimized for the workflow of sending patches, avoiding many ways | |
181 | your existing e-mail client that is optimized for "multipart/*" mime | |
182 | type e-mails to corrupt and render your patches unusable. | |
183 | ||
2de9b711 | 184 | People on the Git mailing list need to be able to read and |
31408251 JH |
185 | comment on the changes you are submitting. It is important for |
186 | a developer to be able to "quote" your changes, using standard | |
187 | e-mail tools, so that they may comment on specific portions of | |
eaa6c987 RS |
188 | your code. For this reason, each patch should be submitted |
189 | "inline" in a separate message. | |
190 | ||
191 | Multiple related patches should be grouped into their own e-mail | |
192 | thread to help readers find all parts of the series. To that end, | |
193 | send them as replies to either an additional "cover letter" message | |
194 | (see below), the first patch, or the respective preceding patch. | |
195 | ||
196 | If your log message (including your name on the | |
7d5bf87b JH |
197 | Signed-off-by line) is not writable in ASCII, make sure that |
198 | you send off a message in the correct encoding. | |
199 | ||
200 | WARNING: Be wary of your MUAs word-wrap | |
45d2b286 JH |
201 | corrupting your patch. Do not cut-n-paste your patch; you can |
202 | lose tabs that way if you are not careful. | |
31408251 | 203 | |
45d2b286 | 204 | It is a common convention to prefix your subject line with |
31408251 | 205 | [PATCH]. This lets people easily distinguish patches from other |
4e891acf JH |
206 | e-mail discussions. Use of additional markers after PATCH and |
207 | the closing bracket to mark the nature of the patch is also | |
208 | encouraged. E.g. [PATCH/RFC] is often used when the patch is | |
209 | not ready to be applied but it is for discussion, [PATCH v2], | |
210 | [PATCH v3] etc. are often seen when you are sending an update to | |
211 | what you have previously sent. | |
31408251 | 212 | |
049e64aa | 213 | `git format-patch` command follows the best current practice to |
31408251 JH |
214 | format the body of an e-mail message. At the beginning of the |
215 | patch should come your commit message, ending with the | |
216 | Signed-off-by: lines, and a line that consists of three dashes, | |
217 | followed by the diffstat information and the patch itself. If | |
218 | you are forwarding a patch from somebody else, optionally, at | |
219 | the beginning of the e-mail message just before the commit | |
220 | message starts, you can put a "From: " line to name that person. | |
221 | ||
222 | You often want to add additional explanation about the patch, | |
223 | other than the commit message itself. Place such "cover letter" | |
86010993 ES |
224 | material between the three-dash line and the diffstat. For |
225 | patches requiring multiple iterations of review and discussion, | |
226 | an explanation of changes between each iteration can be kept in | |
227 | Git-notes and inserted automatically following the three-dash | |
228 | line via `git format-patch --notes`. | |
31408251 | 229 | |
049e64aa | 230 | [[attachment]] |
31408251 | 231 | Do not attach the patch as a MIME attachment, compressed or not. |
e30b217b JH |
232 | Do not let your e-mail client send quoted-printable. Do not let |
233 | your e-mail client send format=flowed which would destroy | |
234 | whitespaces in your patches. Many | |
31408251 JH |
235 | popular e-mail applications will not always transmit a MIME |
236 | attachment as plain text, making it impossible to comment on | |
237 | your code. A MIME attachment also takes a bit more time to | |
238 | process. This does not decrease the likelihood of your | |
239 | MIME-attached change being accepted, but it makes it more likely | |
240 | that it will be postponed. | |
241 | ||
242 | Exception: If your mailer is mangling patches then someone may ask | |
9847f7e0 | 243 | you to re-send them using MIME, that is OK. |
31408251 | 244 | |
049e64aa | 245 | [[pgp-signature]] |
eafd5d94 CW |
246 | Do not PGP sign your patch. Most likely, your maintainer or other people on the |
247 | list would not have your PGP key and would not bother obtaining it anyway. | |
248 | Your patch is not judged by who you are; a good patch from an unknown origin | |
249 | has a far better chance of being accepted than a patch from a known, respected | |
250 | origin that is done poorly or does incorrect things. | |
9847f7e0 JH |
251 | |
252 | If you really really really really want to do a PGP signed | |
253 | patch, format it as "multipart/signed", not a text/plain message | |
049e64aa | 254 | that starts with `-----BEGIN PGP SIGNED MESSAGE-----`. That is |
9847f7e0 JH |
255 | not a text/plain, it's something else. |
256 | ||
7d5bf87b | 257 | Send your patch with "To:" set to the mailing list, with "cc:" listing |
d0c26f0f | 258 | people who are involved in the area you are touching (the output from |
049e64aa | 259 | +git blame _$path_+ and +git shortlog {litdd}no-merges _$path_+ would help to |
7d5bf87b | 260 | identify them), to solicit comments and reviews. |
04d24455 | 261 | |
049e64aa | 262 | :1: footnote:[The current maintainer: gitster@pobox.com] |
263 | :2: footnote:[The mailing list: git@vger.kernel.org] | |
264 | ||
7d5bf87b | 265 | After the list reached a consensus that it is a good idea to apply the |
049e64aa | 266 | patch, re-send it with "To:" set to the maintainer{1} and "cc:" the |
267 | list{2} for inclusion. | |
31408251 | 268 | |
049e64aa | 269 | Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and |
270 | `Tested-by:` lines as necessary to credit people who helped your | |
7d5bf87b | 271 | patch. |
04d24455 | 272 | |
049e64aa | 273 | [[sign-off]] |
274 | === Certify your work by adding your "Signed-off-by: " line | |
31408251 JH |
275 | |
276 | To improve tracking of who did what, we've borrowed the | |
277 | "sign-off" procedure from the Linux kernel project on patches | |
48a8c26c | 278 | that are being emailed around. Although core Git is a lot |
31408251 JH |
279 | smaller project it is a good discipline to follow it. |
280 | ||
281 | The sign-off is a simple line at the end of the explanation for | |
282 | the patch, which certifies that you wrote it or otherwise have | |
283 | the right to pass it on as a open-source patch. The rules are | |
01e60a9a | 284 | pretty simple: if you can certify the below D-C-O: |
31408251 | 285 | |
049e64aa | 286 | [[dco]] |
287 | .Developer's Certificate of Origin 1.1 | |
288 | ____ | |
289 | By making a contribution to this project, I certify that: | |
290 | ||
291 | a. The contribution was created in whole or in part by me and I | |
292 | have the right to submit it under the open source license | |
293 | indicated in the file; or | |
294 | ||
295 | b. The contribution is based upon previous work that, to the best | |
296 | of my knowledge, is covered under an appropriate open source | |
297 | license and I have the right under that license to submit that | |
298 | work with modifications, whether created in whole or in part | |
299 | by me, under the same open source license (unless I am | |
300 | permitted to submit under a different license), as indicated | |
301 | in the file; or | |
302 | ||
303 | c. The contribution was provided directly to me by some other | |
304 | person who certified (a), (b) or (c) and I have not modified | |
305 | it. | |
306 | ||
307 | d. I understand and agree that this project and the contribution | |
308 | are public and that a record of the contribution (including all | |
309 | personal information I submit with it, including my sign-off) is | |
310 | maintained indefinitely and may be redistributed consistent with | |
311 | this project or the open source license(s) involved. | |
312 | ____ | |
31408251 JH |
313 | |
314 | then you just add a line saying | |
315 | ||
049e64aa | 316 | .... |
317 | Signed-off-by: Random J Developer <random@developer.example.org> | |
318 | .... | |
31408251 | 319 | |
2de9b711 | 320 | This line can be automatically added by Git if you run the git-commit |
69945602 PC |
321 | command with the -s option. |
322 | ||
c11c3b56 JH |
323 | Notice that you can place your own Signed-off-by: line when |
324 | forwarding somebody else's patch with the above rules for | |
325 | D-C-O. Indeed you are encouraged to do so. Do not forget to | |
326 | place an in-body "From: " line at the beginning to properly attribute | |
327 | the change to its true author (see (2) above). | |
328 | ||
049e64aa | 329 | [[real-name]] |
67275247 MV |
330 | Also notice that a real name is used in the Signed-off-by: line. Please |
331 | don't hide your real name. | |
332 | ||
049e64aa | 333 | [[commit-trailers]] |
95b7a41a RR |
334 | If you like, you can put extra tags at the end: |
335 | ||
049e64aa | 336 | . `Reported-by:` is used to credit someone who found the bug that |
337 | the patch attempts to fix. | |
338 | . `Acked-by:` says that the person who is more familiar with the area | |
339 | the patch attempts to modify liked the patch. | |
340 | . `Reviewed-by:`, unlike the other tags, can only be offered by the | |
341 | reviewer and means that she is completely satisfied that the patch | |
342 | is ready for application. It is usually offered only after a | |
343 | detailed review. | |
344 | . `Tested-by:` is used to indicate that the person applied the patch | |
345 | and found it to have the desired effect. | |
95b7a41a RR |
346 | |
347 | You can also create your own tag or use one that's in common usage | |
348 | such as "Thanks-to:", "Based-on-patch-by:", or "Mentored-by:". | |
9740d289 | 349 | |
049e64aa | 350 | == Subsystems with dedicated maintainers |
e6da8ee8 JH |
351 | |
352 | Some parts of the system have dedicated maintainers with their own | |
353 | repositories. | |
354 | ||
049e64aa | 355 | - 'git-gui/' comes from git-gui project, maintained by Pat Thoyts: |
e6da8ee8 | 356 | |
049e64aa | 357 | git://repo.or.cz/git-gui.git |
e6da8ee8 | 358 | |
049e64aa | 359 | - 'gitk-git/' comes from Paul Mackerras's gitk project: |
e6da8ee8 | 360 | |
049e64aa | 361 | git://ozlabs.org/~paulus/gitk |
e6da8ee8 | 362 | |
049e64aa | 363 | - 'po/' comes from the localization coordinator, Jiang Xin: |
e6da8ee8 JH |
364 | |
365 | https://github.com/git-l10n/git-po/ | |
366 | ||
367 | Patches to these parts should be based on their trees. | |
368 | ||
049e64aa | 369 | [[patch-flow]] |
370 | == An ideal patch flow | |
a941fb4a JH |
371 | |
372 | Here is an ideal patch flow for this project the current maintainer | |
373 | suggests to the contributors: | |
374 | ||
049e64aa | 375 | . You come up with an itch. You code it up. |
a941fb4a | 376 | |
049e64aa | 377 | . Send it to the list and cc people who may need to know about |
378 | the change. | |
379 | + | |
380 | The people who may need to know are the ones whose code you | |
381 | are butchering. These people happen to be the ones who are | |
382 | most likely to be knowledgeable enough to help you, but | |
383 | they have no obligation to help you (i.e. you ask for help, | |
384 | don't demand). +git log -p {litdd} _$area_you_are_modifying_+ would | |
385 | help you find out who they are. | |
a941fb4a | 386 | |
049e64aa | 387 | . You get comments and suggestions for improvements. You may |
388 | even get them in a "on top of your change" patch form. | |
a941fb4a | 389 | |
049e64aa | 390 | . Polish, refine, and re-send to the list and the people who |
391 | spend their time to improve your patch. Go back to step (2). | |
a941fb4a | 392 | |
049e64aa | 393 | . The list forms consensus that the last round of your patch is |
394 | good. Send it to the maintainer and cc the list. | |
a941fb4a | 395 | |
049e64aa | 396 | . A topic branch is created with the patch and is merged to `next`, |
397 | and cooked further and eventually graduates to `master`. | |
a941fb4a JH |
398 | |
399 | In any time between the (2)-(3) cycle, the maintainer may pick it up | |
049e64aa | 400 | from the list and queue it to `pu`, in order to make it easier for |
a941fb4a JH |
401 | people play with it without having to pick up and apply the patch to |
402 | their trees themselves. | |
403 | ||
049e64aa | 404 | [[patch-status]] |
405 | == Know the status of your patch after submission | |
63cb8215 MM |
406 | |
407 | * You can use Git itself to find out when your patch is merged in | |
049e64aa | 408 | master. `git pull --rebase` will automatically skip already-applied |
63cb8215 MM |
409 | patches, and will let you know. This works only if you rebase on top |
410 | of the branch in which your patch has been merged (i.e. it will not | |
411 | tell you if your patch is merged in pu if you rebase on top of | |
412 | master). | |
413 | ||
2de9b711 | 414 | * Read the Git mailing list, the maintainer regularly posts messages |
63cb8215 MM |
415 | entitled "What's cooking in git.git" and "What's in git.git" giving |
416 | the status of various proposed changes. | |
417 | ||
049e64aa | 418 | [[travis]] |
419 | == GitHub-Travis CI hints | |
0e5d028a LS |
420 | |
421 | With an account at GitHub (you can get one for free to work on open | |
422 | source projects), you can use Travis CI to test your changes on Linux, | |
423 | Mac (and hopefully soon Windows). You can find a successful example | |
424 | test build here: https://travis-ci.org/git/git/builds/120473209 | |
425 | ||
426 | Follow these steps for the initial setup: | |
427 | ||
049e64aa | 428 | . Fork https://github.com/git/git to your GitHub account. |
429 | You can find detailed instructions how to fork here: | |
430 | https://help.github.com/articles/fork-a-repo/ | |
0e5d028a | 431 | |
049e64aa | 432 | . Open the Travis CI website: https://travis-ci.org |
0e5d028a | 433 | |
049e64aa | 434 | . Press the "Sign in with GitHub" button. |
0e5d028a | 435 | |
049e64aa | 436 | . Grant Travis CI permissions to access your GitHub account. |
437 | You can find more information about the required permissions here: | |
438 | https://docs.travis-ci.com/user/github-oauth-scopes | |
0e5d028a | 439 | |
049e64aa | 440 | . Open your Travis CI profile page: https://travis-ci.org/profile |
0e5d028a | 441 | |
049e64aa | 442 | . Enable Travis CI builds for your Git fork. |
0e5d028a LS |
443 | |
444 | After the initial setup, Travis CI will run whenever you push new changes | |
445 | to your fork of Git on GitHub. You can monitor the test state of all your | |
049e64aa | 446 | branches here: https://travis-ci.org/__<Your GitHub handle>__/git/branches |
0e5d028a LS |
447 | |
448 | If a branch did not pass all test cases then it is marked with a red | |
449 | cross. In that case you can click on the failing Travis CI job and | |
450 | scroll all the way down in the log. Find the line "<-- Click here to see | |
451 | detailed test output!" and click on the triangle next to the log line | |
452 | number to expand the detailed test output. Here is such a failing | |
453 | example: https://travis-ci.org/git/git/jobs/122676187 | |
454 | ||
455 | Fix the problem and push your fix to your Git fork. This will trigger | |
456 | a new Travis CI build to ensure all tests pass. | |
457 | ||
049e64aa | 458 | [[mua]] |
459 | == MUA specific hints | |
9740d289 JH |
460 | |
461 | Some of patches I receive or pick up from the list share common | |
462 | patterns of breakage. Please make sure your MUA is set up | |
57756161 JN |
463 | properly not to corrupt whitespaces. |
464 | ||
049e64aa | 465 | See the DISCUSSION section of linkgit:git-format-patch[1] for hints on |
57756161 | 466 | checking your patch by mailing it to yourself and applying with |
049e64aa | 467 | linkgit:git-am[1]. |
57756161 JN |
468 | |
469 | While you are at it, check the resulting commit log message from | |
470 | a trial run of applying the patch. If what is in the resulting | |
471 | commit is not exactly what you would want to see, it is very | |
472 | likely that your maintainer would end up hand editing the log | |
473 | message when he applies your patch. Things like "Hi, this is my | |
474 | first patch.\n", if you really want to put in the patch e-mail, | |
475 | should come after the three-dash line that signals the end of the | |
476 | commit message. | |
9847f7e0 | 477 | |
9740d289 | 478 | |
049e64aa | 479 | === Pine |
9740d289 JH |
480 | |
481 | (Johannes Schindelin) | |
482 | ||
049e64aa | 483 | .... |
9740d289 JH |
484 | I don't know how many people still use pine, but for those poor |
485 | souls it may be good to mention that the quell-flowed-text is | |
486 | needed for recent versions. | |
487 | ||
488 | ... the "no-strip-whitespace-before-send" option, too. AFAIK it | |
489 | was introduced in 4.60. | |
049e64aa | 490 | .... |
9740d289 JH |
491 | |
492 | (Linus Torvalds) | |
493 | ||
049e64aa | 494 | .... |
9740d289 JH |
495 | And 4.58 needs at least this. |
496 | ||
9740d289 JH |
497 | diff-tree 8326dd8350be64ac7fc805f6563a1d61ad10d32c (from e886a61f76edf5410573e92e38ce22974f9c40f1) |
498 | Author: Linus Torvalds <torvalds@g5.osdl.org> | |
499 | Date: Mon Aug 15 17:23:51 2005 -0700 | |
500 | ||
501 | Fix pine whitespace-corruption bug | |
502 | ||
503 | There's no excuse for unconditionally removing whitespace from | |
504 | the pico buffers on close. | |
505 | ||
506 | diff --git a/pico/pico.c b/pico/pico.c | |
507 | --- a/pico/pico.c | |
508 | +++ b/pico/pico.c | |
509 | @@ -219,7 +219,9 @@ PICO *pm; | |
a6080a0a JH |
510 | switch(pico_all_done){ /* prepare for/handle final events */ |
511 | case COMP_EXIT : /* already confirmed */ | |
512 | packheader(); | |
9740d289 | 513 | +#if 0 |
a6080a0a | 514 | stripwhitespace(); |
9740d289 | 515 | +#endif |
a6080a0a JH |
516 | c |= COMP_EXIT; |
517 | break; | |
049e64aa | 518 | .... |
9740d289 | 519 | |
1eb446fa JH |
520 | (Daniel Barkalow) |
521 | ||
049e64aa | 522 | .... |
1eb446fa JH |
523 | > A patch to SubmittingPatches, MUA specific help section for |
524 | > users of Pine 4.63 would be very much appreciated. | |
525 | ||
526 | Ah, it looks like a recent version changed the default behavior to do the | |
527 | right thing, and inverted the sense of the configuration option. (Either | |
528 | that or Gentoo did it.) So you need to set the | |
529 | "no-strip-whitespace-before-send" option, unless the option you have is | |
530 | "strip-whitespace-before-send", in which case you should avoid checking | |
531 | it. | |
049e64aa | 532 | .... |
1eb446fa | 533 | |
049e64aa | 534 | === Thunderbird, KMail, GMail |
9740d289 | 535 | |
049e64aa | 536 | See the MUA-SPECIFIC HINTS section of linkgit:git-format-patch[1]. |
e30b217b | 537 | |
049e64aa | 538 | === Gnus |
e30b217b | 539 | |
049e64aa | 540 | "|" in the `*Summary*` buffer can be used to pipe the current |
e30b217b | 541 | message to an external program, and this is a handy way to drive |
049e64aa | 542 | `git am`. However, if the message is MIME encoded, what is |
e30b217b | 543 | piped into the program is the representation you see in your |
049e64aa | 544 | `*Article*` buffer after unwrapping MIME. This is often not what |
e30b217b JH |
545 | you would want for two reasons. It tends to screw up non ASCII |
546 | characters (most notably in people's names), and also | |
049e64aa | 547 | whitespaces (fatal in patches). Running "C-u g" to display the |
548 | message in raw form before using "|" to run the pipe can work | |
e30b217b | 549 | this problem around. |