a698bafb55
Add footnote about Thunderbird about trimming trailing WS. Signed-off-by: <gitzilla@gmail.com> Signed-off-by: Junio C Hamano <junkio@cox.net>
243 lines
8.6 KiB
Plaintext
243 lines
8.6 KiB
Plaintext
I started reading over the SubmittingPatches document for Linux
|
|
kernel, primarily because I wanted to have a document similar to
|
|
it for the core GIT to make sure people understand what they are
|
|
doing when they write "Signed-off-by" line.
|
|
|
|
But the patch submission requirements are a lot more relaxed
|
|
here, because the core GIT is thousand times smaller ;-). So
|
|
here is only the relevant bits.
|
|
|
|
|
|
(1) Make separate commits for logically separate changes.
|
|
|
|
Unless your patch is really trivial, you should not be sending
|
|
out a patch that was generated between your working tree and
|
|
your commit head. Instead, always make a commit with complete
|
|
commit message and generate a series of patches from your
|
|
repository. It is a good discipline.
|
|
|
|
Describe the technical detail of the change(s).
|
|
|
|
If your description starts to get long, that's a sign that you
|
|
probably need to split up your commit to finer grained pieces.
|
|
|
|
|
|
(2) Generate your patch using git/cogito out of your commits.
|
|
|
|
git diff tools generate unidiff which is the preferred format.
|
|
You do not have to be afraid to use -M option to "git diff" or
|
|
"git format-patch", if your patch involves file renames. The
|
|
receiving end can handle them just fine.
|
|
|
|
Please make sure your patch does not include any extra files
|
|
which do not belong in a patch submission. Make sure to review
|
|
your patch after generating it, to ensure accuracy. Before
|
|
sending out, please make sure it cleanly applies to the "master"
|
|
branch head.
|
|
|
|
|
|
(3) Sending your patches.
|
|
|
|
People on the git mailing list needs to be able to read and
|
|
comment on the changes you are submitting. It is important for
|
|
a developer to be able to "quote" your changes, using standard
|
|
e-mail tools, so that they may comment on specific portions of
|
|
your code. For this reason, all patches should be submitting
|
|
e-mail "inline". WARNING: Be wary of your MUAs word-wrap
|
|
corrupting your patch. Do not cut-n-paste your patch.
|
|
|
|
It is common convention to prefix your subject line with
|
|
[PATCH]. This lets people easily distinguish patches from other
|
|
e-mail discussions.
|
|
|
|
"git format-patch" command follows the best current practice to
|
|
format the body of an e-mail message. At the beginning of the
|
|
patch should come your commit message, ending with the
|
|
Signed-off-by: lines, and a line that consists of three dashes,
|
|
followed by the diffstat information and the patch itself. If
|
|
you are forwarding a patch from somebody else, optionally, at
|
|
the beginning of the e-mail message just before the commit
|
|
message starts, you can put a "From: " line to name that person.
|
|
|
|
You often want to add additional explanation about the patch,
|
|
other than the commit message itself. Place such "cover letter"
|
|
material between the three dash lines and the diffstat.
|
|
|
|
Do not attach the patch as a MIME attachment, compressed or not.
|
|
Do not let your e-mail client send quoted-printable. Many
|
|
popular e-mail applications will not always transmit a MIME
|
|
attachment as plain text, making it impossible to comment on
|
|
your code. A MIME attachment also takes a bit more time to
|
|
process. This does not decrease the likelihood of your
|
|
MIME-attached change being accepted, but it makes it more likely
|
|
that it will be postponed.
|
|
|
|
Exception: If your mailer is mangling patches then someone may ask
|
|
you to re-send them using MIME.
|
|
|
|
Note that your maintainer does not subscribe to the git mailing
|
|
list (he reads it via mail-to-news gateway). If your patch is
|
|
for discussion first, send it "To:" the mailing list, and
|
|
optoinally "cc:" him. If it is trivially correct or after list
|
|
discussion reached consensus, send it "To:" the maintainer and
|
|
optionally "cc:" the list.
|
|
|
|
|
|
(6) Sign your work
|
|
|
|
To improve tracking of who did what, we've borrowed the
|
|
"sign-off" procedure from the Linux kernel project on patches
|
|
that are being emailed around. Although core GIT is a lot
|
|
smaller project it is a good discipline to follow it.
|
|
|
|
The sign-off is a simple line at the end of the explanation for
|
|
the patch, which certifies that you wrote it or otherwise have
|
|
the right to pass it on as a open-source patch. The rules are
|
|
pretty simple: if you can certify the below:
|
|
|
|
Developer's Certificate of Origin 1.1
|
|
|
|
By making a contribution to this project, I certify that:
|
|
|
|
(a) The contribution was created in whole or in part by me and I
|
|
have the right to submit it under the open source license
|
|
indicated in the file; or
|
|
|
|
(b) The contribution is based upon previous work that, to the best
|
|
of my knowledge, is covered under an appropriate open source
|
|
license and I have the right under that license to submit that
|
|
work with modifications, whether created in whole or in part
|
|
by me, under the same open source license (unless I am
|
|
permitted to submit under a different license), as indicated
|
|
in the file; or
|
|
|
|
(c) The contribution was provided directly to me by some other
|
|
person who certified (a), (b) or (c) and I have not modified
|
|
it.
|
|
|
|
(d) I understand and agree that this project and the contribution
|
|
are public and that a record of the contribution (including all
|
|
personal information I submit with it, including my sign-off) is
|
|
maintained indefinitely and may be redistributed consistent with
|
|
this project or the open source license(s) involved.
|
|
|
|
then you just add a line saying
|
|
|
|
Signed-off-by: Random J Developer <random@developer.example.org>
|
|
|
|
Some people also put extra tags at the end. They'll just be ignored for
|
|
now, but you can do this to mark internal company procedures or just
|
|
point out some special detail about the sign-off.
|
|
|
|
|
|
------------------------------------------------
|
|
MUA specific hints
|
|
|
|
Some of patches I receive or pick up from the list share common
|
|
patterns of breakage. Please make sure your MUA is set up
|
|
properly not to corrupt whitespaces. Here are two common ones
|
|
I have seen:
|
|
|
|
* Empty context lines that do not have _any_ whitespace.
|
|
|
|
* Non empty context lines that have one extra whitespace at the
|
|
beginning.
|
|
|
|
|
|
Pine
|
|
----
|
|
|
|
(Johannes Schindelin)
|
|
|
|
I don't know how many people still use pine, but for those poor
|
|
souls it may be good to mention that the quell-flowed-text is
|
|
needed for recent versions.
|
|
|
|
... the "no-strip-whitespace-before-send" option, too. AFAIK it
|
|
was introduced in 4.60.
|
|
|
|
(Linus Torvalds)
|
|
|
|
And 4.58 needs at least this.
|
|
|
|
---
|
|
diff-tree 8326dd8350be64ac7fc805f6563a1d61ad10d32c (from e886a61f76edf5410573e92e38ce22974f9c40f1)
|
|
Author: Linus Torvalds <torvalds@g5.osdl.org>
|
|
Date: Mon Aug 15 17:23:51 2005 -0700
|
|
|
|
Fix pine whitespace-corruption bug
|
|
|
|
There's no excuse for unconditionally removing whitespace from
|
|
the pico buffers on close.
|
|
|
|
diff --git a/pico/pico.c b/pico/pico.c
|
|
--- a/pico/pico.c
|
|
+++ b/pico/pico.c
|
|
@@ -219,7 +219,9 @@ PICO *pm;
|
|
switch(pico_all_done){ /* prepare for/handle final events */
|
|
case COMP_EXIT : /* already confirmed */
|
|
packheader();
|
|
+#if 0
|
|
stripwhitespace();
|
|
+#endif
|
|
c |= COMP_EXIT;
|
|
break;
|
|
|
|
|
|
|
|
Thunderbird
|
|
-----------
|
|
|
|
(A Large Angry SCM)
|
|
|
|
Here are some hints on how to successfully submit patches inline using
|
|
Thunderbird. [*3*]
|
|
|
|
This recipe appears to work with the current [*1*] Thunderbird from Suse.
|
|
|
|
The following Thunderbird extensions are needed:
|
|
AboutConfig 0.5
|
|
http://aboutconfig.mozdev.org/
|
|
External Editor 0.5.4
|
|
http://extensionroom.mozdev.org/more-info/exteditor
|
|
|
|
1) Prepare the patch as a text file using your method of choice.
|
|
|
|
2) Before opening a compose window, use Edit->Account Settings to
|
|
uncheck the "Compose messages in HTML format" setting in the
|
|
"Composition & Addressing" panel of the account to be used to send the
|
|
patch. [*2*]
|
|
|
|
3) In the main Thunderbird window, _before_ you open the compose window
|
|
for the patch, use Tools->about:config to set the following to the
|
|
indicated values:
|
|
mailnews.send_plaintext_flowed => false
|
|
mailnews.wraplength => 999
|
|
|
|
4) Open a compose window and click the external editor icon.
|
|
|
|
5) In the external editor window, read in the patch file and exit the
|
|
editor normally.
|
|
|
|
6) Back in the compose window: Add whatever other text you wish to the
|
|
message, complete the addressing and subject fields, and press send.
|
|
|
|
7) Optionally, undo the about:config/account settings changes made in
|
|
steps 2 & 3.
|
|
|
|
|
|
[Footnotes]
|
|
*1* Version 1.0 (20041207) from the MozillaThunderbird-1.0-5 rpm of Suse
|
|
9.3 professional updates.
|
|
|
|
*2* It may be possible to do this with about:config and the following
|
|
settings but I haven't tried, yet.
|
|
mail.html_compose => false
|
|
mail.identity.default.compose_html => false
|
|
mail.identity.id?.compose_html => false
|
|
|
|
*3* Even after following these hints, Thunderbird will still trim
|
|
trailing whitespace from each line. I currently have no work around for
|
|
for this issue.
|
|
|