@matheusbsbs / matheus-bagliano / commits / 049e64aa50

Documentation: convert SubmittingPatches to AsciiDoc

The SubmittingPatches document is often cited by outside parties as an example of good practices to follow, including logical, independent commits; patch sign-offs; and sending patches to a mailing list. Currently, people who want to cite a particular section tend to either refer to it by name and let the interested party search through the document to find it, or link to a given line number on GitHub and hope the file doesn't change. Instead, convert the document to AsciiDoc. Build it as part of the technical documentation, since it is likely of interest to the same group of people. Provide stable links to the sections which outside parties are likely to want to link to. Make some minor structural changes to organize it so that it can be formatted sanely. Since the makefile needs a .txt extension in order to build with the rest of the documentation, simply copy the file. Ignore the temporary file so it doesn't get checked in accidentally, and remove it as part of the clean process. Do this instead of renaming the file so that people who have already linked to the documentation (who we're trying to help) don't find their links broken. Avoid symlinking since Windows will not like that. This allows us to render the document as part of the website for the benefit of others who wish to link to it as well as providing a more nicely formatted display for our community and potential contributors. Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>

brian m. carlson committed Nov 12, 2017 at 22:07 UTC 049e64aa5024a9fa2fbe6116d413da1ffc7f497a
3 files changed +191 -161
Documentation/.gitignore
+1
@@ -11,3 +11,4 @@ doc.dep
11 cmds-*.txt
12 mergetools-*.txt
13 manpage-base-url.xsl
14 +SubmittingPatches.txt
Documentation/Makefile
+5
@@ -67,6 +67,7 @@ SP_ARTICLES += howto/maintain-git
67 API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt)))
68 SP_ARTICLES += $(API_DOCS)
69
70 +TECH_DOCS += SubmittingPatches
71 TECH_DOCS += technical/hash-function-transition
72 TECH_DOCS += technical/http-protocol
73 TECH_DOCS += technical/index-format
@@ -324,6 +325,7 @@ clean:
325 $(RM) *.pdf
326 $(RM) howto-index.txt howto/*.html doc.dep
327 $(RM) technical/*.html technical/api-index.txt
328 + $(RM) SubmittingPatches.txt
329 $(RM) $(cmds_txt) $(mergetools_txt) *.made
330 $(RM) manpage-base-url.xsl
331
@@ -362,6 +364,9 @@ technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../
364 $(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt asciidoc.conf
365 $(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt
366
367 +SubmittingPatches.txt: SubmittingPatches
368 + $(QUIET_GEN) cp $< $@
369 +
370 XSLT = docbook.xsl
371 XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css
372
Documentation/SubmittingPatches
+185 -161
@@ -1,40 +1,47 @@
1 +Submitting Patches
2 +==================
3 +
4 +== Guidelines
5 +
6 Here are some guidelines for people who want to contribute their code
7 to this software.
8
4 -(0) Decide what to base your work on.
9 +[[base-branch]]
10 +=== Decide what to base your work on.
11
12 In general, always base your work on the oldest branch that your
13 change is relevant to.
14
9 - - A bugfix should be based on 'maint' in general. If the bug is not
10 - present in 'maint', base it on 'master'. For a bug that's not yet
11 - in 'master', find the topic that introduces the regression, and
12 - base your work on the tip of the topic.
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.
19
14 - - A new feature should be based on 'master' in general. If the new
15 - feature depends on a topic that is in 'pu', but not in 'master',
16 - base your work on the tip of that topic.
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.
23
18 - - Corrections and enhancements to a topic not yet in 'master' should
19 - be based on the tip of that topic. If the topic has not been merged
20 - to 'next', it's alright to add a note to squash minor corrections
21 - into the series.
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.
28
23 - - In the exceptional case that a new feature depends on several topics
24 - not in 'master', start working on 'next' or 'pu' privately and send
25 - out patches for discussion. Before the final merge, you may have to
26 - wait until some of the dependent topics graduate to 'master', and
27 - rebase your work.
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.
34
29 - - Some parts of the system have dedicated maintainers with their own
30 - repositories (see the section "Subsystems" below). Changes to
31 - these parts should be based on their trees.
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.
38
33 -To find the tip of a topic branch, run "git log --first-parent
34 -master..pu" and look for the merge commit. The second parent of this
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
41 commit is the tip of the topic branch.
42
37 -(1) Make separate commits for logically separate changes.
43 +[[separate-commits]]
44 +=== Make separate commits for logically separate changes.
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
@@ -58,8 +65,9 @@ differs substantially from the prior version, are all good things
65 to have.
66
67 Make sure that you have tests for the bug you are fixing. See
61 -t/README for guidance.
68 +`t/README` for guidance.
69
70 +[[tests]]
71 When adding a new feature, make sure that you have new tests to show
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
@@ -84,41 +92,45 @@ 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.
94
95 +[[whitespace-check]]
96 Oh, another thing. We are picky about whitespaces. Make sure your
97 changes do not trigger errors with the sample pre-commit hook shipped
89 -in templates/hooks--pre-commit. To help ensure this does not happen,
90 -run "git diff --check" on your changes before you commit.
98 +in `templates/hooks--pre-commit`. To help ensure this does not happen,
99 +run `git diff --check` on your changes before you commit.
100
92 -
93 -(2) Describe your changes well.
101 +[[describe-changes]]
102 +=== Describe your changes well.
103
104 The first line of the commit message should be a short description (50
96 -characters is the soft limit, see DISCUSSION in git-commit(1)), and
97 -should skip the full stop. It is also conventional in most cases to
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
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
101 - . doc: clarify distinction between sign-off and pgp-signing
102 - . githooks.txt: improve the intro section
110 +* doc: clarify distinction between sign-off and pgp-signing
111 +* githooks.txt: improve the intro section
112
104 -If in doubt which identifier to use, run "git log --no-merges" on the
113 +If in doubt which identifier to use, run `git log --no-merges` on the
114 files you are modifying to see the current conventions.
115
116 +[[summary-section]]
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
122 +[[meaningful-message]]
123 The body should provide a meaningful commit message, which:
124
114 - . explains the problem the change tries to solve, i.e. what is wrong
115 - with the current code without the change.
125 +. explains the problem the change tries to solve, i.e. what is wrong
126 + with the current code without the change.
127
117 - . justifies the way the change solves the problem, i.e. why the
118 - result with the change is better.
128 +. justifies the way the change solves the problem, i.e. why the
129 + result with the change is better.
130
120 - . alternate solutions considered but discarded, if any.
131 +. alternate solutions considered but discarded, if any.
132
133 +[[imperative-mood]]
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
@@ -126,36 +138,43 @@ its behavior. Try to make sure your explanation can be understood
138 without external resources. Instead of giving a URL to a mailing list
139 archive, summarize the relevant points of the discussion.
140
141 +[[commit-reference]]
142 If you want to reference a previous commit in the history of a stable
143 branch, use the format "abbreviated sha1 (subject, date)",
144 with the subject enclosed in a pair of double-quotes, like this:
145
133 - Commit f86a374 ("pack-bitmap.c: fix a memleak", 2015-03-30)
134 - noticed that ...
146 +....
147 + Commit f86a374 ("pack-bitmap.c: fix a memleak", 2015-03-30)
148 + noticed that ...
149 +....
150
151 The "Copy commit summary" command of gitk can be used to obtain this
137 -format, or this invocation of "git show":
152 +format, or this invocation of `git show`:
153
139 - git show -s --date=short --pretty='format:%h ("%s", %ad)' <commit>
154 +....
155 + git show -s --date=short --pretty='format:%h ("%s", %ad)' <commit>
156 +....
157
141 -(3) Generate your patch using Git tools out of your commits.
158 +[[git-tools]]
159 +=== Generate your patch using Git tools out of your commits.
160
161 Git based diff tools generate unidiff which is the preferred format.
162
145 -You do not have to be afraid to use -M option to "git diff" or
146 -"git format-patch", if your patch involves file renames. The
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
165 receiving end can handle them just fine.
166
167 +[[review-patch]]
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
171 your patch after generating it, to ensure accuracy. Before
153 -sending out, please make sure it cleanly applies to the "master"
172 +sending out, please make sure it cleanly applies to the `master`
173 branch head. If you are preparing a work based on "next" branch,
174 that is fine, but please mark it as such.
175
157 -
158 -(4) Sending your patches.
176 +[[send-patches]]
177 +=== Sending your patches.
178
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
@@ -191,7 +210,7 @@ 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.
212
194 -"git format-patch" command follows the best current practice to
213 +`git format-patch` command follows the best current practice to
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,
@@ -208,6 +227,7 @@ 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`.
229
230 +[[attachment]]
231 Do not attach the patch as a MIME attachment, compressed or not.
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
@@ -222,6 +242,7 @@ that it will be postponed.
242 Exception: If your mailer is mangling patches then someone may ask
243 you to re-send them using MIME, that is OK.
244
245 +[[pgp-signature]]
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
@@ -230,28 +251,27 @@ origin that is done poorly or does incorrect things.
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
233 -that starts with '-----BEGIN PGP SIGNED MESSAGE-----'. That is
254 +that starts with `-----BEGIN PGP SIGNED MESSAGE-----`. That is
255 not a text/plain, it's something else.
256
257 Send your patch with "To:" set to the mailing list, with "cc:" listing
258 people who are involved in the area you are touching (the output from
238 -"git blame $path" and "git shortlog --no-merges $path" would help to
259 ++git blame _$path_+ and +git shortlog {litdd}no-merges _$path_+ would help to
260 identify them), to solicit comments and reviews.
261
262 +:1: footnote:[The current maintainer: gitster@pobox.com]
263 +:2: footnote:[The mailing list: git@vger.kernel.org]
264 +
265 After the list reached a consensus that it is a good idea to apply the
242 -patch, re-send it with "To:" set to the maintainer [*1*] and "cc:" the
243 -list [*2*] for inclusion.
266 +patch, re-send it with "To:" set to the maintainer{1} and "cc:" the
267 +list{2} for inclusion.
268
245 -Do not forget to add trailers such as "Acked-by:", "Reviewed-by:" and
246 -"Tested-by:" lines as necessary to credit people who helped your
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
271 patch.
272
249 - [Addresses]
250 - *1* The current maintainer: gitster@pobox.com
251 - *2* The mailing list: git@vger.kernel.org
252 -
253 -
254 -(5) Certify your work by adding your "Signed-off-by: " line
273 +[[sign-off]]
274 +=== Certify your work by adding your "Signed-off-by: " line
275
276 To improve tracking of who did what, we've borrowed the
277 "sign-off" procedure from the Linux kernel project on patches
@@ -263,35 +283,39 @@ 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
284 pretty simple: if you can certify the below D-C-O:
285
266 - Developer's Certificate of Origin 1.1
267 -
268 - By making a contribution to this project, I certify that:
269 -
270 - (a) The contribution was created in whole or in part by me and I
271 - have the right to submit it under the open source license
272 - indicated in the file; or
273 -
274 - (b) The contribution is based upon previous work that, to the best
275 - of my knowledge, is covered under an appropriate open source
276 - license and I have the right under that license to submit that
277 - work with modifications, whether created in whole or in part
278 - by me, under the same open source license (unless I am
279 - permitted to submit under a different license), as indicated
280 - in the file; or
281 -
282 - (c) The contribution was provided directly to me by some other
283 - person who certified (a), (b) or (c) and I have not modified
284 - it.
285 -
286 - (d) I understand and agree that this project and the contribution
287 - are public and that a record of the contribution (including all
288 - personal information I submit with it, including my sign-off) is
289 - maintained indefinitely and may be redistributed consistent with
290 - this project or the open source license(s) involved.
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 +____
313
314 then you just add a line saying
315
294 - Signed-off-by: Random J Developer <random@developer.example.org>
316 +....
317 + Signed-off-by: Random J Developer <random@developer.example.org>
318 +....
319
320 This line can be automatically added by Git if you run the git-commit
321 command with the -s option.
@@ -302,85 +326,86 @@ 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
329 +[[real-name]]
330 Also notice that a real name is used in the Signed-off-by: line. Please
331 don't hide your real name.
332
333 +[[commit-trailers]]
334 If you like, you can put extra tags at the end:
335
310 -1. "Reported-by:" is used to credit someone who found the bug that
311 - the patch attempts to fix.
312 -2. "Acked-by:" says that the person who is more familiar with the area
313 - the patch attempts to modify liked the patch.
314 -3. "Reviewed-by:", unlike the other tags, can only be offered by the
315 - reviewer and means that she is completely satisfied that the patch
316 - is ready for application. It is usually offered only after a
317 - detailed review.
318 -4. "Tested-by:" is used to indicate that the person applied the patch
319 - and found it to have the desired effect.
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.
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:".
349
324 -------------------------------------------------
325 -Subsystems with dedicated maintainers
350 +== Subsystems with dedicated maintainers
351
352 Some parts of the system have dedicated maintainers with their own
353 repositories.
354
330 - - git-gui/ comes from git-gui project, maintained by Pat Thoyts:
355 +- 'git-gui/' comes from git-gui project, maintained by Pat Thoyts:
356
332 - git://repo.or.cz/git-gui.git
357 + git://repo.or.cz/git-gui.git
358
334 - - gitk-git/ comes from Paul Mackerras's gitk project:
359 +- 'gitk-git/' comes from Paul Mackerras's gitk project:
360
336 - git://ozlabs.org/~paulus/gitk
361 + git://ozlabs.org/~paulus/gitk
362
338 - - po/ comes from the localization coordinator, Jiang Xin:
363 +- 'po/' comes from the localization coordinator, Jiang Xin:
364
365 https://github.com/git-l10n/git-po/
366
367 Patches to these parts should be based on their trees.
368
344 -------------------------------------------------
345 -An ideal patch flow
369 +[[patch-flow]]
370 +== An ideal patch flow
371
372 Here is an ideal patch flow for this project the current maintainer
373 suggests to the contributors:
374
350 - (0) You come up with an itch. You code it up.
375 +. You come up with an itch. You code it up.
376
352 - (1) Send it to the list and cc people who may need to know about
353 - the change.
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.
386
355 - The people who may need to know are the ones whose code you
356 - are butchering. These people happen to be the ones who are
357 - most likely to be knowledgeable enough to help you, but
358 - they have no obligation to help you (i.e. you ask for help,
359 - don't demand). "git log -p -- $area_you_are_modifying" would
360 - help you find out who they are.
387 +. You get comments and suggestions for improvements. You may
388 + even get them in a "on top of your change" patch form.
389
362 - (2) You get comments and suggestions for improvements. You may
363 - even get them in a "on top of your change" patch form.
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).
392
365 - (3) Polish, refine, and re-send to the list and the people who
366 - spend their time to improve your patch. Go back to step (2).
393 +. The list forms consensus that the last round of your patch is
394 + good. Send it to the maintainer and cc the list.
395
368 - (4) The list forms consensus that the last round of your patch is
369 - good. Send it to the maintainer and cc the list.
370 -
371 - (5) A topic branch is created with the patch and is merged to 'next',
372 - and cooked further and eventually graduates to 'master'.
396 +. A topic branch is created with the patch and is merged to `next`,
397 + and cooked further and eventually graduates to `master`.
398
399 In any time between the (2)-(3) cycle, the maintainer may pick it up
375 -from the list and queue it to 'pu', in order to make it easier for
400 +from the list and queue it to `pu`, in order to make it easier for
401 people play with it without having to pick up and apply the patch to
402 their trees themselves.
403
379 -------------------------------------------------
380 -Know the status of your patch after submission
404 +[[patch-status]]
405 +== Know the status of your patch after submission
406
407 * You can use Git itself to find out when your patch is merged in
383 - master. 'git pull --rebase' will automatically skip already-applied
408 + master. `git pull --rebase` will automatically skip already-applied
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
@@ -390,8 +415,8 @@ Know the status of your patch after submission
415 entitled "What's cooking in git.git" and "What's in git.git" giving
416 the status of various proposed changes.
417
393 ---------------------------------------------------
394 -GitHub-Travis CI hints
418 +[[travis]]
419 +== GitHub-Travis CI hints
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,
@@ -400,25 +425,25 @@ test build here: https://travis-ci.org/git/git/builds/120473209
425
426 Follow these steps for the initial setup:
427
403 - (1) Fork https://github.com/git/git to your GitHub account.
404 - You can find detailed instructions how to fork here:
405 - https://help.github.com/articles/fork-a-repo/
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/
431
407 - (2) Open the Travis CI website: https://travis-ci.org
432 +. Open the Travis CI website: https://travis-ci.org
433
409 - (3) Press the "Sign in with GitHub" button.
434 +. Press the "Sign in with GitHub" button.
435
411 - (4) Grant Travis CI permissions to access your GitHub account.
412 - You can find more information about the required permissions here:
413 - https://docs.travis-ci.com/user/github-oauth-scopes
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
439
415 - (5) Open your Travis CI profile page: https://travis-ci.org/profile
440 +. Open your Travis CI profile page: https://travis-ci.org/profile
441
417 - (6) Enable Travis CI builds for your Git fork.
442 +. Enable Travis CI builds for your Git fork.
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
421 -branches here: https://travis-ci.org/<Your GitHub handle>/git/branches
446 +branches here: https://travis-ci.org/__<Your GitHub handle>__/git/branches
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
@@ -430,17 +455,16 @@ example: https://travis-ci.org/git/git/jobs/122676187
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
433 -
434 -------------------------------------------------
435 -MUA specific hints
458 +[[mua]]
459 +== MUA specific hints
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
463 properly not to corrupt whitespaces.
464
441 -See the DISCUSSION section of git-format-patch(1) for hints on
465 +See the DISCUSSION section of linkgit:git-format-patch[1] for hints on
466 checking your patch by mailing it to yourself and applying with
443 -git-am(1).
467 +linkgit:git-am[1].
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
@@ -452,23 +476,24 @@ should come after the three-dash line that signals the end of the
476 commit message.
477
478
455 -Pine
456 -----
479 +=== Pine
480
481 (Johannes Schindelin)
482
483 +....
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.
490 +....
491
492 (Linus Torvalds)
493
494 +....
495 And 4.58 needs at least this.
496
471 ----
497 diff-tree 8326dd8350be64ac7fc805f6563a1d61ad10d32c (from e886a61f76edf5410573e92e38ce22974f9c40f1)
498 Author: Linus Torvalds <torvalds@g5.osdl.org>
499 Date: Mon Aug 15 17:23:51 2005 -0700
@@ -490,10 +515,11 @@ diff --git a/pico/pico.c b/pico/pico.c
515 +#endif
516 c |= COMP_EXIT;
517 break;
493 -
518 +....
519
520 (Daniel Barkalow)
521
522 +....
523 > A patch to SubmittingPatches, MUA specific help section for
524 > users of Pine 4.63 would be very much appreciated.
525
@@ -503,23 +529,21 @@ 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.
532 +....
533
534 +=== Thunderbird, KMail, GMail
535
508 -Thunderbird, KMail, GMail
509 --------------------------
510 -
511 -See the MUA-SPECIFIC HINTS section of git-format-patch(1).
536 +See the MUA-SPECIFIC HINTS section of linkgit:git-format-patch[1].
537
513 -Gnus
514 -----
538 +=== Gnus
539
516 -'|' in the *Summary* buffer can be used to pipe the current
540 +"|" in the `*Summary*` buffer can be used to pipe the current
541 message to an external program, and this is a handy way to drive
518 -"git am". However, if the message is MIME encoded, what is
542 +`git am`. However, if the message is MIME encoded, what is
543 piped into the program is the representation you see in your
520 -*Article* buffer after unwrapping MIME. This is often not what
544 +`*Article*` buffer after unwrapping MIME. This is often not what
545 you would want for two reasons. It tends to screw up non ASCII
546 characters (most notably in people's names), and also
523 -whitespaces (fatal in patches). Running 'C-u g' to display the
524 -message in raw form before using '|' to run the pipe can work
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
549 this problem around.