diff options
Diffstat (limited to 'Documentation/SubmittingPatches')
-rw-r--r-- | Documentation/SubmittingPatches | 53 |
1 files changed, 51 insertions, 2 deletions
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 34fdc83ad4..76fc84d878 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -6,9 +6,13 @@ Checklist (and a short version for the impatient): - 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 + - the body should provide a meaningful commit message, which: + - uses the imperative, present tense: "change", + not "changed" or "changes". + - includes motivation for the change, and contrasts + its implementation with previous behaviour - if you want your work included in git.git, add a "Signed-off-by: Your Name <you@example.com>" line to the commit message (or just use the option "-s" when @@ -62,6 +66,14 @@ Describe the technical detail of the change(s). 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. +That being said, patches which plainly describe the things that +help reviewers check the patch, and future maintainers understand +the code, are the most beautiful patches. Descriptions that summarise +the point in the subject well, and describe the motivation for the +change, the approach taken by the change, and if relevant how this +differs substantially from the prior version, can be found on Usenet +archives back into the late 80's. Consider it like good Netiquette, +but for code. Oh, another thing. I am picky about whitespaces. Make sure your changes do not trigger errors with the sample pre-commit hook shipped @@ -71,7 +83,7 @@ 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 +We try to support a 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. @@ -376,9 +388,36 @@ Thunderbird (A Large Angry SCM) +By default, Thunderbird will both wrap emails as well as flag them as +being 'format=flowed', both of which will make the resulting email unusable +by git. + Here are some hints on how to successfully submit patches inline using Thunderbird. +There are two different approaches. One approach is to configure +Thunderbird to not mangle patches. The second approach is to use +an external editor to keep Thunderbird from mangling the patches. + +Approach #1 (configuration): + +This recipe is current as of Thunderbird 2.0.0.19. Three steps: + 1. Configure your mail server composition as plain text + Edit...Account Settings...Composition & Addressing, + uncheck 'Compose Messages in HTML'. + 2. Configure your general composition window to not wrap + Edit..Preferences..Composition, wrap plain text messages at 0 + 3. Disable the use of format=flowed + Edit..Preferences..Advanced..Config Editor. Search for: + mailnews.send_plaintext_flowed + toggle it to make sure it is set to 'false'. + +After that is done, you should be able to compose email as you +otherwise would (cut + paste, git-format-patch | git-imap-send, etc), +and the patches should not be mangled. + +Approach #2 (external editor): + This recipe appears to work with the current [*1*] Thunderbird from Suse. The following Thunderbird extensions are needed: @@ -464,6 +503,12 @@ message, complete the addressing and subject fields, and press send. Gmail ----- +GMail does not appear to have any way to turn off line wrapping in the web +interface, so this will mangle any emails that you send. You can however +use any IMAP email client to connect to the google imap server, and forward +the emails through that. Just make sure to disable line wrapping in that +email client. Alternatively, use "git send-email" instead. + Submitting properly formatted patches via Gmail is simple now that IMAP support is available. First, edit your ~/.gitconfig to specify your account settings: @@ -476,6 +521,9 @@ account settings: port = 993 sslverify = false +You might need to instead use: folder = "[Google Mail]/Drafts" if you get an error +that the "Folder doesn't exist". + Next, ensure that your Gmail settings are correct. In "Settings" the "Use Unicode (UTF-8) encoding for outgoing messages" should be checked. @@ -486,3 +534,4 @@ command to send the patch emails to your Gmail Drafts folder. Go to your Gmail account, open the Drafts folder, find the patch email, fill in the To: and CC: fields and send away! + |