1Checklist (and a short version for the impatient): 2 3 Commits: 4 5 - make commits of logical units 6 - check for unnecessary whitespace with "git diff --check" 7 before committing 8 - do not check in commented out code or unneeded files 9 - provide a meaningful commit message 10 - the first line of the commit message should be a short 11 description and should skip the full stop 12 - if you want your work included in git.git, add a 13 "Signed-off-by: Your Name <your@email.com>" line to the 14 commit message (or just use the option "-s" when 15 committing) to confirm that you agree to the Developer's 16 Certificate of Origin 17 18 Patch: 19 20 - use "git format-patch -M" to create the patch 21 - send your patch to <git@vger.kernel.org>. If you use 22 git-send-email(1), please test it first by sending 23 email to yourself. 24 - do not PGP sign your patch 25 - do not attach your patch, but read in the mail 26 body, unless you cannot teach your mailer to 27 leave the formatting of the patch alone. 28 - be careful doing cut & paste into your mailer, not to 29 corrupt whitespaces. 30 - provide additional information (which is unsuitable for 31 the commit message) between the "---" and the diffstat 32 - send the patch to the list _and_ the maintainer 33 - if you change, add, or remove a command line option or 34 make some other user interface change, the associated 35 documentation should be updated as well. 36 37Long version: 38 39I started reading over the SubmittingPatches document for Linux 40kernel, primarily because I wanted to have a document similar to 41it for the core GIT to make sure people understand what they are 42doing when they write "Signed-off-by" line. 43 44But the patch submission requirements are a lot more relaxed 45here on the technical/contents front, because the core GIT is 46thousand times smaller ;-). So here is only the relevant bits. 47 48 49(1) Make separate commits for logically separate changes. 50 51Unless your patch is really trivial, you should not be sending 52out a patch that was generated between your working tree and 53your commit head. Instead, always make a commit with complete 54commit message and generate a series of patches from your 55repository. It is a good discipline. 56 57Describe the technical detail of the change(s). 58 59If your description starts to get too long, that's a sign that you 60probably need to split up your commit to finer grained pieces. 61 62Oh, another thing. I am picky about whitespaces. Make sure your 63changes do not trigger errors with the sample pre-commit hook shipped 64in templates/hooks--pre-commit. To help ensure this does not happen, 65run git diff --check on your changes before you commit. 66 67 68(1a) Try to be nice to older C compilers 69 70We try to support wide range of C compilers to compile 71git with. That means that you should not use C99 initializers, even 72if a lot of compilers grok it. 73 74Also, variables have to be declared at the beginning of the block 75(you can check this with gcc, using the -Wdeclaration-after-statement 76option). 77 78Another thing: NULL pointers shall be written as NULL, not as 0. 79 80 81(2) Generate your patch using git tools out of your commits. 82 83git based diff tools (git, Cogito, and StGIT included) generate 84unidiff which is the preferred format. 85 86You do not have to be afraid to use -M option to "git diff" or 87"git format-patch", if your patch involves file renames. The 88receiving end can handle them just fine. 89 90Please make sure your patch does not include any extra files 91which do not belong in a patch submission. Make sure to review 92your patch after generating it, to ensure accuracy. Before 93sending out, please make sure it cleanly applies to the "master" 94branch head. If you are preparing a work based on "next" branch, 95that is fine, but please mark it as such. 96 97 98(3) Sending your patches. 99 100People on the git mailing list need to be able to read and 101comment on the changes you are submitting. It is important for 102a developer to be able to "quote" your changes, using standard 103e-mail tools, so that they may comment on specific portions of 104your code. For this reason, all patches should be submitted 105"inline". WARNING: Be wary of your MUAs word-wrap 106corrupting your patch. Do not cut-n-paste your patch; you can 107lose tabs that way if you are not careful. 108 109It is a common convention to prefix your subject line with 110[PATCH]. This lets people easily distinguish patches from other 111e-mail discussions. 112 113"git format-patch" command follows the best current practice to 114format the body of an e-mail message. At the beginning of the 115patch should come your commit message, ending with the 116Signed-off-by: lines, and a line that consists of three dashes, 117followed by the diffstat information and the patch itself. If 118you are forwarding a patch from somebody else, optionally, at 119the beginning of the e-mail message just before the commit 120message starts, you can put a "From: " line to name that person. 121 122You often want to add additional explanation about the patch, 123other than the commit message itself. Place such "cover letter" 124material between the three dash lines and the diffstat. 125 126Do not attach the patch as a MIME attachment, compressed or not. 127Do not let your e-mail client send quoted-printable. Do not let 128your e-mail client send format=flowed which would destroy 129whitespaces in your patches. Many 130popular e-mail applications will not always transmit a MIME 131attachment as plain text, making it impossible to comment on 132your code. A MIME attachment also takes a bit more time to 133process. This does not decrease the likelihood of your 134MIME-attached change being accepted, but it makes it more likely 135that it will be postponed. 136 137Exception: If your mailer is mangling patches then someone may ask 138you to re-send them using MIME, that is OK. 139 140Do not PGP sign your patch, at least for now. Most likely, your 141maintainer or other people on the list would not have your PGP 142key and would not bother obtaining it anyway. Your patch is not 143judged by who you are; a good patch from an unknown origin has a 144far better chance of being accepted than a patch from a known, 145respected origin that is done poorly or does incorrect things. 146 147If you really really really really want to do a PGP signed 148patch, format it as "multipart/signed", not a text/plain message 149that starts with '-----BEGIN PGP SIGNED MESSAGE-----'. That is 150not a text/plain, it's something else. 151 152Note that your maintainer does not necessarily read everything 153on the git mailing list. If your patch is for discussion first, 154send it "To:" the mailing list, and optionally "cc:" him. If it 155is trivially correct or after the list reached a consensus, send 156it "To:" the maintainer and optionally "cc:" the list. 157 158Also note that your maintainer does not actively involve himself in 159maintaining what are in contrib/ hierarchy. When you send fixes and 160enhancements to them, do not forget to "cc: " the person who primarily 161worked on that hierarchy in contrib/. 162 163 164(4) Sign your work 165 166To improve tracking of who did what, we've borrowed the 167"sign-off" procedure from the Linux kernel project on patches 168that are being emailed around. Although core GIT is a lot 169smaller project it is a good discipline to follow it. 170 171The sign-off is a simple line at the end of the explanation for 172the patch, which certifies that you wrote it or otherwise have 173the right to pass it on as a open-source patch. The rules are 174pretty simple: if you can certify the below: 175 176 Developer's Certificate of Origin 1.1 177 178 By making a contribution to this project, I certify that: 179 180 (a) The contribution was created in whole or in part by me and I 181 have the right to submit it under the open source license 182 indicated in the file; or 183 184 (b) The contribution is based upon previous work that, to the best 185 of my knowledge, is covered under an appropriate open source 186 license and I have the right under that license to submit that 187 work with modifications, whether created in whole or in part 188 by me, under the same open source license (unless I am 189 permitted to submit under a different license), as indicated 190 in the file; or 191 192 (c) The contribution was provided directly to me by some other 193 person who certified (a), (b) or (c) and I have not modified 194 it. 195 196 (d) I understand and agree that this project and the contribution 197 are public and that a record of the contribution (including all 198 personal information I submit with it, including my sign-off) is 199 maintained indefinitely and may be redistributed consistent with 200 this project or the open source license(s) involved. 201 202then you just add a line saying 203 204 Signed-off-by: Random J Developer <random@developer.example.org> 205 206This line can be automatically added by git if you run the git-commit 207command with the -s option. 208 209Some people also put extra tags at the end. They'll just be ignored for 210now, but you can do this to mark internal company procedures or just 211point out some special detail about the sign-off. 212 213 214------------------------------------------------ 215MUA specific hints 216 217Some of patches I receive or pick up from the list share common 218patterns of breakage. Please make sure your MUA is set up 219properly not to corrupt whitespaces. Here are two common ones 220I have seen: 221 222* Empty context lines that do not have _any_ whitespace. 223 224* Non empty context lines that have one extra whitespace at the 225 beginning. 226 227One test you could do yourself if your MUA is set up correctly is: 228 229* Send the patch to yourself, exactly the way you would, except 230 To: and Cc: lines, which would not contain the list and 231 maintainer address. 232 233* Save that patch to a file in UNIX mailbox format. Call it say 234 a.patch. 235 236* Try to apply to the tip of the "master" branch from the 237 git.git public repository: 238 239 $ git fetch http://kernel.org/pub/scm/git/git.git master:test-apply 240 $ git checkout test-apply 241 $ git reset --hard 242 $ git applymbox a.patch 243 244If it does not apply correctly, there can be various reasons. 245 246* Your patch itself does not apply cleanly. That is _bad_ but 247 does not have much to do with your MUA. Please rebase the 248 patch appropriately. 249 250* Your MUA corrupted your patch; applymbox would complain that 251 the patch does not apply. Look at .dotest/ subdirectory and 252 see what 'patch' file contains and check for the common 253 corruption patterns mentioned above. 254 255* While you are at it, check what are in 'info' and 256 'final-commit' files as well. If what is in 'final-commit' is 257 not exactly what you would want to see in the commit log 258 message, it is very likely that your maintainer would end up 259 hand editing the log message when he applies your patch. 260 Things like "Hi, this is my first patch.\n", if you really 261 want to put in the patch e-mail, should come after the 262 three-dash line that signals the end of the commit message. 263 264 265Pine 266---- 267 268(Johannes Schindelin) 269 270I don't know how many people still use pine, but for those poor 271souls it may be good to mention that the quell-flowed-text is 272needed for recent versions. 273 274... the "no-strip-whitespace-before-send" option, too. AFAIK it 275was introduced in 4.60. 276 277(Linus Torvalds) 278 279And 4.58 needs at least this. 280 281--- 282diff-tree 8326dd8350be64ac7fc805f6563a1d61ad10d32c (from e886a61f76edf5410573e92e38ce22974f9c40f1) 283Author: Linus Torvalds <torvalds@g5.osdl.org> 284Date: Mon Aug 15 17:23:51 2005 -0700 285 286 Fix pine whitespace-corruption bug 287 288 There's no excuse for unconditionally removing whitespace from 289 the pico buffers on close. 290 291diff --git a/pico/pico.c b/pico/pico.c 292--- a/pico/pico.c 293+++ b/pico/pico.c 294@@ -219,7 +219,9 @@ PICO *pm; 295 switch(pico_all_done){ /* prepare for/handle final events */ 296 case COMP_EXIT : /* already confirmed */ 297 packheader(); 298+#if 0 299 stripwhitespace(); 300+#endif 301 c |= COMP_EXIT; 302 break; 303 304 305(Daniel Barkalow) 306 307> A patch to SubmittingPatches, MUA specific help section for 308> users of Pine 4.63 would be very much appreciated. 309 310Ah, it looks like a recent version changed the default behavior to do the 311right thing, and inverted the sense of the configuration option. (Either 312that or Gentoo did it.) So you need to set the 313"no-strip-whitespace-before-send" option, unless the option you have is 314"strip-whitespace-before-send", in which case you should avoid checking 315it. 316 317 318Thunderbird 319----------- 320 321(A Large Angry SCM) 322 323Here are some hints on how to successfully submit patches inline using 324Thunderbird. 325 326This recipe appears to work with the current [*1*] Thunderbird from Suse. 327 328The following Thunderbird extensions are needed: 329 AboutConfig 0.5 330 http://aboutconfig.mozdev.org/ 331 External Editor 0.7.2 332 http://globs.org/articles.php?lng=en&pg=8 333 3341) Prepare the patch as a text file using your method of choice. 335 3362) Before opening a compose window, use Edit->Account Settings to 337uncheck the "Compose messages in HTML format" setting in the 338"Composition & Addressing" panel of the account to be used to send the 339patch. [*2*] 340 3413) In the main Thunderbird window, _before_ you open the compose window 342for the patch, use Tools->about:config to set the following to the 343indicated values: 344 mailnews.send_plaintext_flowed => false 345 mailnews.wraplength => 0 346 3474) Open a compose window and click the external editor icon. 348 3495) In the external editor window, read in the patch file and exit the 350editor normally. 351 3526) Back in the compose window: Add whatever other text you wish to the 353message, complete the addressing and subject fields, and press send. 354 3557) Optionally, undo the about:config/account settings changes made in 356steps 2 & 3. 357 358 359[Footnotes] 360*1* Version 1.0 (20041207) from the MozillaThunderbird-1.0-5 rpm of Suse 3619.3 professional updates. 362 363*2* It may be possible to do this with about:config and the following 364settings but I haven't tried, yet. 365 mail.html_compose => false 366 mail.identity.default.compose_html => false 367 mail.identity.id?.compose_html => false 368 369 370Gnus 371---- 372 373'|' in the *Summary* buffer can be used to pipe the current 374message to an external program, and this is a handy way to drive 375"git am". However, if the message is MIME encoded, what is 376piped into the program is the representation you see in your 377*Article* buffer after unwrapping MIME. This is often not what 378you would want for two reasons. It tends to screw up non ASCII 379characters (most notably in people's names), and also 380whitespaces (fatal in patches). Running 'C-u g' to display the 381message in raw form before using '|' to run the pipe can work 382this problem around. 383 384 385KMail 386----- 387 388This should help you to submit patches inline using KMail. 389 3901) Prepare the patch as a text file. 391 3922) Click on New Mail. 393 3943) Go under "Options" in the Composer window and be sure that 395"Word wrap" is not set. 396 3974) Use Message -> Insert file... and insert the patch. 398 3995) Back in the compose window: add whatever other text you wish to the 400message, complete the addressing and subject fields, and press send.