blob: ec2d3d653dfc733b8511d2332b74df6e42423555 [file] [log] [blame]
Checklist (and a short version for the impatient):
- Make commits of logical units.
- Check for unnecessary whitespace with "git diff --check"
before committing.
- Do not check in commented out code or unneeded files.
- Provide a meaningful commit message.
- The first line of the commit message should be a short
description and should skip the full stop.
- If you want your work included in StGit, add a
"Signed-off-by: Your Name <>" line to the
commit message (or just use the option "-s" when
committing) to confirm that you agree to the Developer's
Certificate of Origin.
- Make sure that you have tests for the bug you are fixing.
- Make sure that the test suite passes after your commit.
- Preferably use "stg mail" to send patches. The first time,
it's a good idea to try to mail the patches to yourself to
see that everything works.
- Do not PGP sign your patch.
- Do not attach your patch, but read in the mail.
body, unless you cannot teach your mailer to
leave the formatting of the patch alone.
- Be careful doing cut & paste into your mailer, not to
corrupt whitespaces.
- Provide additional information (which is unsuitable for the
commit message) between the "---" and the diffstat. (The -E
option to stg mail lets you edit the message before you send
it out.)
- If you change, add, or remove a command line option or
make some other user interface change, the associated
documentation should be updated as well.
- If your name is not writable in ASCII, make sure that
you send off a message in the correct encoding.
- Send the patch to the list ( and the
maintainer ( if (and only if) the
patch is ready for inclusion.
Long version:
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 too long, that's a sign that you
probably need to split up your commit to finer grained pieces.
Oh, another thing. I am picky about whitespaces. Please run git
diff --check on your changes before you commit.
2. Generate your patch using Git tools out of your commits.
Git based diff tools (Git, Cogito, and StGit included) generate
unidiff which is the preferred format.
You do not have to be afraid to use -M option to "git diff" and
friends, 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. If you
are preparing a work based on some other branch, that is fine, but
please mark it as such.
3. Sending your patches.
StGit patches should be sent to the Git mailing list
(, and preferably CCed to the StGit maintainer
( The recipients need 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 submitted "inline".
WARNING: Be wary of your MUAs word-wrap corrupting your patch. Do
not cut-n-paste your patch; you can lose tabs that way if you are
not careful.
It is a common convention to prefix your subject line with [StGit
PATCH]. This lets people easily distinguish patches to StGit from
other e-mail discussions and patches meant for Git itself. Use of
additional markers after PATCH and the closing bracket to mark the
nature of the patch is also encouraged. E.g. [PATCH/RFC] is often
used when the patch is not ready to be applied but it is for
discussion, [PATCH v2], [PATCH v3] etc. are often seen when you are
sending an update to what you have previously sent.
"stg mail" 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. If you have comments
about a whole series of patches, you can include them in a separate
cover mail message (the -e option to stg mail).
Do not attach the patch as a MIME attachment, compressed or not. Do
not let your e-mail client send quoted-printable. Do not let your
e-mail client send format=flowed which would destroy whitespaces in
your patches. 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, that is OK.
Do not PGP sign your patch, at least for now. Most likely, your
maintainer or other people on the list would not have your PGP key
and would not bother obtaining it anyway. Your patch is not judged
by who you are; a good patch from an unknown origin has a far
better chance of being accepted than a patch from a known,
respected origin that is done poorly or does incorrect things.
4. Sign your work
To improve tracking of who did what, we've borrowed the "sign-off"
procedure from the Git and Linux kernel projects on patches that
are being emailed around. Although StGit 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 <>
This line can be automatically added by StGit by any command that
accepts the --sign option.
Notice that you can place your own Signed-off-by: line when
forwarding somebody else's patch with the above rules for D-C-O.
Indeed you are encouraged to do so. Do not forget to place an
in-body "From: " line at the beginning to properly attribute the
change to its true author (see (2) above).
Also notice that a real name is used in the Signed-off-by: line.
Please don't hide your real name.
Some people also put extra tags at the end.
"Acked-by:" says that the patch was reviewed by a person who is
more familiar with the issues and the area the patch attempts to
modify. "Tested-by:" says the patch was tested by the person and
found to have the desired effect.
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
One test you could do yourself if your MUA is set up correctly is:
* Send the patch to yourself, exactly the way you would, except
To: and Cc: lines, which would not contain the list and
maintainer address.
* Save that patch to a file in UNIX mailbox format. Call it say
* Try to apply to the tip of the "master" branch from the
public repository:
$ git fetch master:test-apply
$ git checkout test-apply
$ git reset --hard
$ stg init
$ stg import -M a.patch
If it does not apply correctly, there can be various reasons.
* Your patch itself does not apply cleanly. That is _bad_ but
does not have much to do with your MUA. Please rebase the
patch appropriately.
* Your MUA corrupted your patch; "stg import" would complain that
the patch does not apply.
* Check the imported patch with e.g. "stg show". If it isn't exactly
what you would want to see in the commit log message, it is very
likely that the maintainer would end up hand editing the log
message when he applies your patch. Things like "Hi, this is my
first patch.\n", if you really want to put in the patch e-mail,
should come after the three-dash line that signals the end of the
commit message.
(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 <>
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 */
+#if 0
(Daniel Barkalow)
> A patch to SubmittingPatches, MUA specific help section for
> users of Pine 4.63 would be very much appreciated.
Ah, it looks like a recent version changed the default behavior to do the
right thing, and inverted the sense of the configuration option. (Either
that or Gentoo did it.) So you need to set the
"no-strip-whitespace-before-send" option, unless the option you have is
"strip-whitespace-before-send", in which case you should avoid checking
(A Large Angry SCM)
Here are some hints on how to successfully submit patches inline using
This recipe appears to work with the current [*1*] Thunderbird from Suse.
The following Thunderbird extensions are needed:
AboutConfig 0.5
External Editor 0.7.2
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 => 0
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.
*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 => false
(Lukas Sandström)
There is a script in contrib/thunderbird-patch-inline which can help
you include patches with Thunderbird in an easy way. To use it, do the
steps above and then use the script as the external editor.
'|' in the *Summary* buffer can be used to pipe the current
message to an external program, and this is a handy way to drive
"git am". However, if the message is MIME encoded, what is
piped into the program is the representation you see in your
*Article* buffer after unwrapping MIME. This is often not what
you would want for two reasons. It tends to screw up non ASCII
characters (most notably in people's names), and also
whitespaces (fatal in patches). Running 'C-u g' to display the
message in raw form before using '|' to run the pipe can work
this problem around.
This should help you to submit patches inline using KMail.
1) Prepare the patch as a text file.
2) Click on New Mail.
3) Go under "Options" in the Composer window and be sure that
"Word wrap" is not set.
4) Use Message -> Insert file... and insert the patch.
5) Back in the compose window: add whatever other text you wish to the
message, complete the addressing and subject fields, and press send.
Submitting properly formatted patches via Gmail is simple now that
IMAP support is available. First, edit your ~/.gitconfig to specify your
account settings:
folder = "[Gmail]/Drafts"
host = imaps://
user =
pass = p4ssw0rd
port = 993
sslverify = false
Next, ensure that your Gmail settings are correct. In "Settings" the
"Use Unicode (UTF-8) encoding for outgoing messages" should be checked.
Once your commits are ready to send to the mailing list, run the following
command to send the patch emails to your Gmail Drafts folder.
$ git format-patch -M --stdout origin/master | git imap-send
Go to your Gmail account, open the Drafts folder, find the patch email, fill
in the To: and CC: fields and send away!