X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=Documentation%2FSubmittingPatches;h=8601949e80991823145a6d4c61cb5da918f98275;hb=1a82e79315ed633f6b0b1fc4076054950c5380d3;hp=15b917f78601fe0446dfb40bc5a055893b3804b7;hpb=9740d289ee76097a2ec43e59f7ecb8974bcf8634;p=git.git diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 15b917f7..8601949e 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -4,8 +4,8 @@ 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. +here on the technical/contents front, because the core GIT is +thousand times smaller ;-). So here is only the relevant bits. (1) Make separate commits for logically separate changes. @@ -18,13 +18,19 @@ 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 +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. Make sure your +changes do not trigger errors with the sample pre-commit hook shipped +in templates/hooks--pre-commit. -(2) Generate your patch using git/cogito out of your commits. -git diff tools generate unidiff which is the preferred format. +(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" or "git format-patch", if your patch involves file renames. The receiving end can handle them just fine. @@ -33,20 +39,22 @@ 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. +branch head. If you are preparing a work based on "next" branch, +that is fine, but please mark it as such. (3) Sending your patches. -People on the git mailing list needs to be able to read and +People on the git mailing list 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 submitting -e-mail "inline". WARNING: Be wary of your MUAs word-wrap -corrupting your patch. Do not cut-n-paste your patch. +your code. For this reason, all patches should be submited +"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 common convention to prefix your subject line with +It is a common convention to prefix your subject line with [PATCH]. This lets people easily distinguish patches from other e-mail discussions. @@ -73,14 +81,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. + +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. -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. +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 +162,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 +240,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 ----------- @@ -198,8 +266,8 @@ 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 + External Editor 0.7.2 + http://globs.org/articles.php?lng=en&pg=8 1) Prepare the patch as a text file using your method of choice. @@ -212,7 +280,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 +304,3 @@ settings but I haven't tried, yet. mail.identity.default.compose_html => false mail.identity.id?.compose_html => false - -