Merge branch 'maint' of git://repo.or.cz/git-gui into maint
[gitweb.git] / Documentation / SubmittingPatches
index 90722c21fad453791f53d1e8b62df23450622eae..131bcff9b2367d63d7c8960487893bfcbfcfaa40 100644 (file)
@@ -1,3 +1,30 @@
+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 git.git, add a
+         "Signed-off-by: Your Name <your@email.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
+       - do not PGP sign your patch
+       - use "git format-patch -M" to create the 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
+
+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 +50,8 @@ 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.
 
 
 (2) Generate your patch using git tools out of your commits.
@@ -72,7 +100,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
@@ -101,8 +131,13 @@ 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.
 
+Also note that your maintainer does not actively involve himself in
+maintaining what are in contrib/ hierarchy.  When you send fixes and
+enhancements to them, do not forget to "cc: " the person who primarily
+worked on that hierarchy in contrib/.
+
 
-(6) Sign your work
+(4) Sign your work
 
 To improve tracking of who did what, we've borrowed the
 "sign-off" procedure from the Linux kernel project on patches
@@ -144,6 +179,9 @@ then you just add a line saying
 
        Signed-off-by: Random J Developer <random@developer.example.org>
 
+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.
@@ -304,3 +342,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.