X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=Documentation%2FSubmittingPatches;h=b94d9a816664333e0b1767c22d1639b8839cee24;hb=8e29f903eb366b2d2e846dc35ec4510d2cb263ad;hp=646b6e73318e04cfff7b20abd5d06be424bce503;hpb=3fbe2d54d7d91378934df7b16d70dc5877586fae;p=git.git diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 646b6e733..b94d9a816 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -1,3 +1,41 @@ +Checklist (and a short version for the impatient): + + Commits: + + - 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 git.git, 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 + + Patch: + + - use "git format-patch -M" to create the patch + - send your patch to . 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 + 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 + - 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. + +Long version: + 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 @@ -23,7 +61,21 @@ 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. +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. @@ -72,7 +124,9 @@ 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 +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 @@ -312,3 +366,35 @@ settings but I haven't tried, yet. mail.identity.default.compose_html => false mail.identity.id?.compose_html => false + +Gnus +---- + +'|' 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. + + +KMail +----- + +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.