Merge branch 'master'
[gitweb.git] / Documentation / SubmittingPatches
index 15b917f78601fe0446dfb40bc5a055893b3804b7..9ccb8f72edd0b6a108ea9e9b218039169b90e297 100644 (file)
@@ -73,14 +73,25 @@ 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.
+you to re-send them using MIME, that is OK.
 
-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.
+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.
+
+If you really really really really want to do a PGP signed
+patch, format it as "multipart/signed", not a text/plain message
+that starts with '-----BEGIN PGP SIGNED MESSAGE-----'.  That is
+not a text/plain, it's something else.
+
+Note that your maintainer does not necessarily read everything
+on the git mailing list.  If your patch is for discussion first,
+send it "To:" the mailing list, and optionally "cc:" him.  If it
+is trivially correct or after the list reached a consensus, send
+it "To:" the maintainer and optionally "cc:" the list.
 
 
 (6) Sign your work
@@ -143,6 +154,43 @@ I have seen:
 * Non empty context lines that have one extra whitespace at the
   beginning.
 
+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
+  a.patch.
+
+* Try to apply to the tip of the "master" branch from the
+  git.git public repository:
+
+    $ git fetch http://kernel.org/pub/scm/git/git.git master:test-apply
+    $ git checkout test-apply
+    $ git reset --hard
+    $ git applymbox 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; applymbox would complain that
+  the patch does not apply.  Look at .dotest/ subdirectory and
+  see what 'patch' file contains and check for the common
+  corruption patterns mentioned above.
+
+* While you are at it, check what are in 'info' and
+  'final-commit' files as well.  If what is in 'final-commit' is
+  not exactly what you would want to see in the commit log
+  message, it is very likely that your 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.
+
 
 Pine
 ----
@@ -184,6 +232,18 @@ diff --git a/pico/pico.c b/pico/pico.c
                break;
  
 
+(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
+it.
+
 
 Thunderbird
 -----------
@@ -212,7 +272,7 @@ patch. [*2*]
 for the patch, use Tools->about:config to set the following to the
 indicated values:
        mailnews.send_plaintext_flowed  => false
-       mailnews.wraplength             => 999
+       mailnews.wraplength             => 0
 
 4) Open a compose window and click the external editor icon.
 
@@ -236,5 +296,3 @@ settings but I haven't tried, yet.
        mail.identity.default.compose_html      => false
        mail.identity.id?.compose_html          => false
 
-
-