Merge branch 'maint-1.5.6' into maint-1.6.0
[gitweb.git] / Documentation / SubmittingPatches
index 6a4da2ddd94093aaa03656303c40a5b20bae2fef..34fdc83ad48f764ebc7908a947cd057350c3674d 100644 (file)
@@ -10,17 +10,16 @@ Checklist (and a short version for the impatient):
        - 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 git.git, add a
-         "Signed-off-by: Your Name <your@email.com>" line to the
+         "Signed-off-by: Your Name <you@example.com>" 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
 
        Patch:
 
        - use "git format-patch -M" to create the patch
-       - send your patch to <git@vger.kernel.org>. If you use
-         git-send-email(1), please test it first by sending
-         email to yourself.
        - do not PGP sign your patch
        - do not attach your patch, but read in the mail
          body, unless you cannot teach your mailer to
@@ -29,10 +28,15 @@ Checklist (and a short version for the impatient):
          corrupt whitespaces.
        - provide additional information (which is unsuitable for
          the commit message) between the "---" and the diffstat
-       - send the patch to the list _and_ the maintainer
        - 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 (git@vger.kernel.org) and the
+         maintainer (gitster@pobox.com) if (and only if) the patch
+         is ready for inclusion. If you use git-send-email(1),
+         please test it first by sending email to yourself.
 
 Long version:
 
@@ -65,6 +69,19 @@ in templates/hooks--pre-commit.  To help ensure this does not happen,
 run git diff --check on your changes before you commit.
 
 
+(1a) Try to be nice to older C compilers
+
+We try to support wide range of C compilers to compile
+git with. That means that you should not use C99 initializers, even
+if a lot of compilers grok it.
+
+Also, variables have to be declared at the beginning of the block
+(you can check this with gcc, using the -Wdeclaration-after-statement
+option).
+
+Another thing: NULL pointers shall be written as NULL, not as 0.
+
+
 (2) Generate your patch using git tools out of your commits.
 
 git based diff tools (git, Cogito, and StGIT included) generate
@@ -95,7 +112,12 @@ lose tabs that way if you are not careful.
 
 It is a common convention to prefix your subject line with
 [PATCH].  This lets people easily distinguish patches from other
-e-mail discussions.
+e-mail discussions.  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.
 
 "git format-patch" command follows the best current practice to
 format the body of an e-mail message.  At the beginning of the
@@ -140,7 +162,8 @@ 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.
+it "To:" the maintainer and optionally "cc:" the list for
+inclusion.
 
 Also note that your maintainer does not actively involve himself in
 maintaining what are in contrib/ hierarchy.  When you send fixes and
@@ -193,10 +216,56 @@ then you just add a line saying
 This line can be automatically added by git if you run the git-commit
 command with the -s option.
 
-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.
+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 the 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.
+
+------------------------------------------------
+An ideal patch flow
+
+Here is an ideal patch flow for this project the current maintainer
+suggests to the contributors:
+
+ (0) You come up with an itch.  You code it up.
+
+ (1) Send it to the list and cc people who may need to know about
+     the change.
+
+     The people who may need to know are the ones whose code you
+     are butchering.  These people happen to be the ones who are
+     most likely to be knowledgeable enough to help you, but
+     they have no obligation to help you (i.e. you ask for help,
+     don't demand).  "git log -p -- $area_you_are_modifying" would
+     help you find out who they are.
+
+ (2) You get comments and suggestions for improvements.  You may
+     even get them in a "on top of your change" patch form.
+
+ (3) Polish, refine, and re-send to the list and the people who
+     spend their time to improve your patch.  Go back to step (2).
+
+ (4) The list forms consensus that the last round of your patch is
+     good.  Send it to the list and cc the maintainer.
+
+ (5) A topic branch is created with the patch and is merged to 'next',
+     and cooked further and eventually graduates to 'master'.
+
+In any time between the (2)-(3) cycle, the maintainer may pick it up
+from the list and queue it to 'pu', in order to make it easier for
+people play with it without having to pick up and apply the patch to
+their trees themselves.
 
 ------------------------------------------------
 MUA specific hints
@@ -226,7 +295,7 @@ One test you could do yourself if your MUA is set up correctly is:
     $ git fetch http://kernel.org/pub/scm/git/git.git master:test-apply
     $ git checkout test-apply
     $ git reset --hard
-    $ git applymbox a.patch
+    $ git am a.patch
 
 If it does not apply correctly, there can be various reasons.
 
@@ -234,8 +303,8 @@ If it does not apply correctly, there can be various reasons.
   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
+* Your MUA corrupted your patch; "am" would complain that
+  the patch does not apply.  Look at .git/rebase-apply/ subdirectory and
   see what 'patch' file contains and check for the common
   corruption patterns mentioned above.
 
@@ -279,15 +348,15 @@ 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();
+           switch(pico_all_done){      /* prepare for/handle final events */
+             case COMP_EXIT :          /* already confirmed */
+               packheader();
 +#if 0
-               stripwhitespace();
+               stripwhitespace();
 +#endif
-               c |= COMP_EXIT;
-               break;
+               c |= COMP_EXIT;
+               break;
+
 
 (Daniel Barkalow)
 
@@ -353,6 +422,11 @@ settings but I haven't tried, yet.
        mail.identity.default.compose_html      => false
        mail.identity.id?.compose_html          => 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.
 
 Gnus
 ----
@@ -385,3 +459,30 @@ This should help you to submit patches inline using KMail.
 
 5) Back in the compose window: add whatever other text you wish to the
 message, complete the addressing and subject fields, and press send.
+
+
+Gmail
+-----
+
+Submitting properly formatted patches via Gmail is simple now that
+IMAP support is available. First, edit your ~/.gitconfig to specify your
+account settings:
+
+[imap]
+       folder = "[Gmail]/Drafts"
+       host = imaps://imap.gmail.com
+       user = user@gmail.com
+       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!