1Here are some guidelines for people who want to contribute their code 2to this software. 3 4(0) Decide what to base your work on. 5 6In general, always base your work on the oldest branch that your 7change is relevant to. 8 9 - A bugfix should be based on 'maint' in general. If the bug is not 10 present in 'maint', base it on 'master'. For a bug that's not yet 11 in 'master', find the topic that introduces the regression, and 12 base your work on the tip of the topic. 13 14 - A new feature should be based on 'master' in general. If the new 15 feature depends on a topic that is in 'pu', but not in 'master', 16 base your work on the tip of that topic. 17 18 - Corrections and enhancements to a topic not yet in 'master' should 19 be based on the tip of that topic. If the topic has not been merged 20 to 'next', it's alright to add a note to squash minor corrections 21 into the series. 22 23 - In the exceptional case that a new feature depends on several topics 24 not in 'master', start working on 'next' or 'pu' privately and send 25 out patches for discussion. Before the final merge, you may have to 26 wait until some of the dependent topics graduate to 'master', and 27 rebase your work. 28 29 - Some parts of the system have dedicated maintainers with their own 30 repositories (see the section "Subsystems" below). Changes to 31 these parts should be based on their trees. 32 33To find the tip of a topic branch, run "git log --first-parent 34master..pu" and look for the merge commit. The second parent of this 35commit is the tip of the topic branch. 36 37(1) Make separate commits for logically separate changes. 38 39Unless your patch is really trivial, you should not be sending 40out a patch that was generated between your working tree and 41your commit head. Instead, always make a commit with complete 42commit message and generate a series of patches from your 43repository. It is a good discipline. 44 45Give an explanation for the change(s) that is detailed enough so 46that people can judge if it is good thing to do, without reading 47the actual patch text to determine how well the code does what 48the explanation promises to do. 49 50If your description starts to get too long, that's a sign that you 51probably need to split up your commit to finer grained pieces. 52That being said, patches which plainly describe the things that 53help reviewers check the patch, and future maintainers understand 54the code, are the most beautiful patches. Descriptions that summarise 55the point in the subject well, and describe the motivation for the 56change, the approach taken by the change, and if relevant how this 57differs substantially from the prior version, are all good things 58to have. 59 60Make sure that you have tests for the bug you are fixing. See 61t/README for guidance. 62 63When adding a new feature, make sure that you have new tests to show 64the feature triggers the new behavior when it should, and to show the 65feature does not trigger when it shouldn't. After any code change, make 66sure that the entire test suite passes. 67 68If you have an account at GitHub (and you can get one for free to work 69on open source projects), you can use their Travis CI integration to 70test your changes on Linux, Mac (and hopefully soon Windows). See 71GitHub-Travis CI hints section for details. 72 73Do not forget to update the documentation to describe the updated 74behavior and make sure that the resulting documentation set formats 75well. It is currently a liberal mixture of US and UK English norms for 76spelling and grammar, which is somewhat unfortunate. A huge patch that 77touches the files all over the place only to correct the inconsistency 78is not welcome, though. Potential clashes with other changes that can 79result from such a patch are not worth it. We prefer to gradually 80reconcile the inconsistencies in favor of US English, with small and 81easily digestible patches, as a side effect of doing some other real 82work in the vicinity (e.g. rewriting a paragraph for clarity, while 83turning en_UK spelling to en_US). Obvious typographical fixes are much 84more welcomed ("teh -> "the"), preferably submitted as independent 85patches separate from other documentation changes. 86 87Oh, another thing. We are picky about whitespaces. Make sure your 88changes do not trigger errors with the sample pre-commit hook shipped 89in templates/hooks--pre-commit. To help ensure this does not happen, 90run git diff --check on your changes before you commit. 91 92 93(2) Describe your changes well. 94 95The first line of the commit message should be a short description (50 96characters is the soft limit, see DISCUSSION in git-commit(1)), and 97should skip the full stop. It is also conventional in most cases to 98prefix the first line with "area: " where the area is a filename or 99identifier for the general area of the code being modified, e.g. 100 101 . archive: ustar header checksum is computed unsigned 102 . git-cherry-pick.txt: clarify the use of revision range notation 103 104If in doubt which identifier to use, run "git log --no-merges" on the 105files you are modifying to see the current conventions. 106 107The body should provide a meaningful commit message, which: 108 109 . explains the problem the change tries to solve, iow, what is wrong 110 with the current code without the change. 111 112 . justifies the way the change solves the problem, iow, why the 113 result with the change is better. 114 115 . alternate solutions considered but discarded, if any. 116 117Describe your changes in imperative mood, e.g. "make xyzzy do frotz" 118instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy 119to do frotz", as if you are giving orders to the codebase to change 120its behaviour. Try to make sure your explanation can be understood 121without external resources. Instead of giving a URL to a mailing list 122archive, summarize the relevant points of the discussion. 123 124If you want to reference a previous commit in the history of a stable 125branch use the format "abbreviated sha1 (subject, date)". So for example 126like this: "Commit f86a374 (pack-bitmap.c: fix a memleak, 2015-03-30) 127noticed [...]". 128 129 130(3) Generate your patch using Git tools out of your commits. 131 132Git based diff tools generate unidiff which is the preferred format. 133 134You do not have to be afraid to use -M option to "git diff" or 135"git format-patch", if your patch involves file renames. The 136receiving end can handle them just fine. 137 138Please make sure your patch does not add commented out debugging code, 139or include any extra files which do not relate to what your patch 140is trying to achieve. Make sure to review 141your patch after generating it, to ensure accuracy. Before 142sending out, please make sure it cleanly applies to the "master" 143branch head. If you are preparing a work based on "next" branch, 144that is fine, but please mark it as such. 145 146 147(4) Sending your patches. 148 149Learn to use format-patch and send-email if possible. These commands 150are optimized for the workflow of sending patches, avoiding many ways 151your existing e-mail client that is optimized for "multipart/*" mime 152type e-mails to corrupt and render your patches unusable. 153 154People on the Git mailing list need to be able to read and 155comment on the changes you are submitting. It is important for 156a developer to be able to "quote" your changes, using standard 157e-mail tools, so that they may comment on specific portions of 158your code. For this reason, each patch should be submitted 159"inline" in a separate message. 160 161Multiple related patches should be grouped into their own e-mail 162thread to help readers find all parts of the series. To that end, 163send them as replies to either an additional "cover letter" message 164(see below), the first patch, or the respective preceding patch. 165 166If your log message (including your name on the 167Signed-off-by line) is not writable in ASCII, make sure that 168you send off a message in the correct encoding. 169 170WARNING: Be wary of your MUAs word-wrap 171corrupting your patch. Do not cut-n-paste your patch; you can 172lose tabs that way if you are not careful. 173 174It is a common convention to prefix your subject line with 175[PATCH]. This lets people easily distinguish patches from other 176e-mail discussions. Use of additional markers after PATCH and 177the closing bracket to mark the nature of the patch is also 178encouraged. E.g. [PATCH/RFC] is often used when the patch is 179not ready to be applied but it is for discussion, [PATCH v2], 180[PATCH v3] etc. are often seen when you are sending an update to 181what you have previously sent. 182 183"git format-patch" command follows the best current practice to 184format the body of an e-mail message. At the beginning of the 185patch should come your commit message, ending with the 186Signed-off-by: lines, and a line that consists of three dashes, 187followed by the diffstat information and the patch itself. If 188you are forwarding a patch from somebody else, optionally, at 189the beginning of the e-mail message just before the commit 190message starts, you can put a "From: " line to name that person. 191 192You often want to add additional explanation about the patch, 193other than the commit message itself. Place such "cover letter" 194material between the three-dash line and the diffstat. For 195patches requiring multiple iterations of review and discussion, 196an explanation of changes between each iteration can be kept in 197Git-notes and inserted automatically following the three-dash 198line via `git format-patch --notes`. 199 200Do not attach the patch as a MIME attachment, compressed or not. 201Do not let your e-mail client send quoted-printable. Do not let 202your e-mail client send format=flowed which would destroy 203whitespaces in your patches. Many 204popular e-mail applications will not always transmit a MIME 205attachment as plain text, making it impossible to comment on 206your code. A MIME attachment also takes a bit more time to 207process. This does not decrease the likelihood of your 208MIME-attached change being accepted, but it makes it more likely 209that it will be postponed. 210 211Exception: If your mailer is mangling patches then someone may ask 212you to re-send them using MIME, that is OK. 213 214Do not PGP sign your patch, at least for now. Most likely, your 215maintainer or other people on the list would not have your PGP 216key and would not bother obtaining it anyway. Your patch is not 217judged by who you are; a good patch from an unknown origin has a 218far better chance of being accepted than a patch from a known, 219respected origin that is done poorly or does incorrect things. 220 221If you really really really really want to do a PGP signed 222patch, format it as "multipart/signed", not a text/plain message 223that starts with '-----BEGIN PGP SIGNED MESSAGE-----'. That is 224not a text/plain, it's something else. 225 226Send your patch with "To:" set to the mailing list, with "cc:" listing 227people who are involved in the area you are touching (the output from 228"git blame $path" and "git shortlog --no-merges $path" would help to 229identify them), to solicit comments and reviews. 230 231After the list reached a consensus that it is a good idea to apply the 232patch, re-send it with "To:" set to the maintainer [*1*] and "cc:" the 233list [*2*] for inclusion. 234 235Do not forget to add trailers such as "Acked-by:", "Reviewed-by:" and 236"Tested-by:" lines as necessary to credit people who helped your 237patch. 238 239 [Addresses] 240 *1* The current maintainer: gitster@pobox.com 241 *2* The mailing list: git@vger.kernel.org 242 243 244(5) Sign your work 245 246To improve tracking of who did what, we've borrowed the 247"sign-off" procedure from the Linux kernel project on patches 248that are being emailed around. Although core Git is a lot 249smaller project it is a good discipline to follow it. 250 251The sign-off is a simple line at the end of the explanation for 252the patch, which certifies that you wrote it or otherwise have 253the right to pass it on as a open-source patch. The rules are 254pretty simple: if you can certify the below: 255 256 Developer's Certificate of Origin 1.1 257 258 By making a contribution to this project, I certify that: 259 260 (a) The contribution was created in whole or in part by me and I 261 have the right to submit it under the open source license 262 indicated in the file; or 263 264 (b) The contribution is based upon previous work that, to the best 265 of my knowledge, is covered under an appropriate open source 266 license and I have the right under that license to submit that 267 work with modifications, whether created in whole or in part 268 by me, under the same open source license (unless I am 269 permitted to submit under a different license), as indicated 270 in the file; or 271 272 (c) The contribution was provided directly to me by some other 273 person who certified (a), (b) or (c) and I have not modified 274 it. 275 276 (d) I understand and agree that this project and the contribution 277 are public and that a record of the contribution (including all 278 personal information I submit with it, including my sign-off) is 279 maintained indefinitely and may be redistributed consistent with 280 this project or the open source license(s) involved. 281 282then you just add a line saying 283 284 Signed-off-by: Random J Developer <random@developer.example.org> 285 286This line can be automatically added by Git if you run the git-commit 287command with the -s option. 288 289Notice that you can place your own Signed-off-by: line when 290forwarding somebody else's patch with the above rules for 291D-C-O. Indeed you are encouraged to do so. Do not forget to 292place an in-body "From: " line at the beginning to properly attribute 293the change to its true author (see (2) above). 294 295Also notice that a real name is used in the Signed-off-by: line. Please 296don't hide your real name. 297 298If you like, you can put extra tags at the end: 299 3001. "Reported-by:" is used to credit someone who found the bug that 301 the patch attempts to fix. 3022. "Acked-by:" says that the person who is more familiar with the area 303 the patch attempts to modify liked the patch. 3043. "Reviewed-by:", unlike the other tags, can only be offered by the 305 reviewer and means that she is completely satisfied that the patch 306 is ready for application. It is usually offered only after a 307 detailed review. 3084. "Tested-by:" is used to indicate that the person applied the patch 309 and found it to have the desired effect. 310 311You can also create your own tag or use one that's in common usage 312such as "Thanks-to:", "Based-on-patch-by:", or "Mentored-by:". 313 314------------------------------------------------ 315Subsystems with dedicated maintainers 316 317Some parts of the system have dedicated maintainers with their own 318repositories. 319 320 - git-gui/ comes from git-gui project, maintained by Pat Thoyts: 321 322 git://repo.or.cz/git-gui.git 323 324 - gitk-git/ comes from Paul Mackerras's gitk project: 325 326 git://ozlabs.org/~paulus/gitk 327 328 - po/ comes from the localization coordinator, Jiang Xin: 329 330 https://github.com/git-l10n/git-po/ 331 332Patches to these parts should be based on their trees. 333 334------------------------------------------------ 335An ideal patch flow 336 337Here is an ideal patch flow for this project the current maintainer 338suggests to the contributors: 339 340 (0) You come up with an itch. You code it up. 341 342 (1) Send it to the list and cc people who may need to know about 343 the change. 344 345 The people who may need to know are the ones whose code you 346 are butchering. These people happen to be the ones who are 347 most likely to be knowledgeable enough to help you, but 348 they have no obligation to help you (i.e. you ask for help, 349 don't demand). "git log -p -- $area_you_are_modifying" would 350 help you find out who they are. 351 352 (2) You get comments and suggestions for improvements. You may 353 even get them in a "on top of your change" patch form. 354 355 (3) Polish, refine, and re-send to the list and the people who 356 spend their time to improve your patch. Go back to step (2). 357 358 (4) The list forms consensus that the last round of your patch is 359 good. Send it to the maintainer and cc the list. 360 361 (5) A topic branch is created with the patch and is merged to 'next', 362 and cooked further and eventually graduates to 'master'. 363 364In any time between the (2)-(3) cycle, the maintainer may pick it up 365from the list and queue it to 'pu', in order to make it easier for 366people play with it without having to pick up and apply the patch to 367their trees themselves. 368 369------------------------------------------------ 370Know the status of your patch after submission 371 372* You can use Git itself to find out when your patch is merged in 373 master. 'git pull --rebase' will automatically skip already-applied 374 patches, and will let you know. This works only if you rebase on top 375 of the branch in which your patch has been merged (i.e. it will not 376 tell you if your patch is merged in pu if you rebase on top of 377 master). 378 379* Read the Git mailing list, the maintainer regularly posts messages 380 entitled "What's cooking in git.git" and "What's in git.git" giving 381 the status of various proposed changes. 382 383-------------------------------------------------- 384GitHub-Travis CI hints 385 386With an account at GitHub (you can get one for free to work on open 387source projects), you can use Travis CI to test your changes on Linux, 388Mac (and hopefully soon Windows). You can find a successful example 389test build here: https://travis-ci.org/git/git/builds/120473209 390 391Follow these steps for the initial setup: 392 393 (1) Fork https://github.com/git/git to your GitHub account. 394 You can find detailed instructions how to fork here: 395 https://help.github.com/articles/fork-a-repo/ 396 397 (2) Open the Travis CI website: https://travis-ci.org 398 399 (3) Press the "Sign in with GitHub" button. 400 401 (4) Grant Travis CI permissions to access your GitHub account. 402 You can find more information about the required permissions here: 403 https://docs.travis-ci.com/user/github-oauth-scopes 404 405 (5) Open your Travis CI profile page: https://travis-ci.org/profile 406 407 (6) Enable Travis CI builds for your Git fork. 408 409After the initial setup, Travis CI will run whenever you push new changes 410to your fork of Git on GitHub. You can monitor the test state of all your 411branches here: https://travis-ci.org/<Your GitHub handle>/git/branches 412 413If a branch did not pass all test cases then it is marked with a red 414cross. In that case you can click on the failing Travis CI job and 415scroll all the way down in the log. Find the line "<-- Click here to see 416detailed test output!" and click on the triangle next to the log line 417number to expand the detailed test output. Here is such a failing 418example: https://travis-ci.org/git/git/jobs/122676187 419 420Fix the problem and push your fix to your Git fork. This will trigger 421a new Travis CI build to ensure all tests pass. 422 423 424------------------------------------------------ 425MUA specific hints 426 427Some of patches I receive or pick up from the list share common 428patterns of breakage. Please make sure your MUA is set up 429properly not to corrupt whitespaces. 430 431See the DISCUSSION section of git-format-patch(1) for hints on 432checking your patch by mailing it to yourself and applying with 433git-am(1). 434 435While you are at it, check the resulting commit log message from 436a trial run of applying the patch. If what is in the resulting 437commit is not exactly what you would want to see, it is very 438likely that your maintainer would end up hand editing the log 439message when he applies your patch. Things like "Hi, this is my 440first patch.\n", if you really want to put in the patch e-mail, 441should come after the three-dash line that signals the end of the 442commit message. 443 444 445Pine 446---- 447 448(Johannes Schindelin) 449 450I don't know how many people still use pine, but for those poor 451souls it may be good to mention that the quell-flowed-text is 452needed for recent versions. 453 454... the "no-strip-whitespace-before-send" option, too. AFAIK it 455was introduced in 4.60. 456 457(Linus Torvalds) 458 459And 4.58 needs at least this. 460 461--- 462diff-tree 8326dd8350be64ac7fc805f6563a1d61ad10d32c (from e886a61f76edf5410573e92e38ce22974f9c40f1) 463Author: Linus Torvalds <torvalds@g5.osdl.org> 464Date: Mon Aug 15 17:23:51 2005 -0700 465 466 Fix pine whitespace-corruption bug 467 468 There's no excuse for unconditionally removing whitespace from 469 the pico buffers on close. 470 471diff --git a/pico/pico.c b/pico/pico.c 472--- a/pico/pico.c 473+++ b/pico/pico.c 474@@ -219,7 +219,9 @@ PICO *pm; 475 switch(pico_all_done){ /* prepare for/handle final events */ 476 case COMP_EXIT : /* already confirmed */ 477 packheader(); 478+#if 0 479 stripwhitespace(); 480+#endif 481 c |= COMP_EXIT; 482 break; 483 484 485(Daniel Barkalow) 486 487> A patch to SubmittingPatches, MUA specific help section for 488> users of Pine 4.63 would be very much appreciated. 489 490Ah, it looks like a recent version changed the default behavior to do the 491right thing, and inverted the sense of the configuration option. (Either 492that or Gentoo did it.) So you need to set the 493"no-strip-whitespace-before-send" option, unless the option you have is 494"strip-whitespace-before-send", in which case you should avoid checking 495it. 496 497 498Thunderbird, KMail, GMail 499------------------------- 500 501See the MUA-SPECIFIC HINTS section of git-format-patch(1). 502 503Gnus 504---- 505 506'|' in the *Summary* buffer can be used to pipe the current 507message to an external program, and this is a handy way to drive 508"git am". However, if the message is MIME encoded, what is 509piped into the program is the representation you see in your 510*Article* buffer after unwrapping MIME. This is often not what 511you would want for two reasons. It tends to screw up non ASCII 512characters (most notably in people's names), and also 513whitespaces (fatal in patches). Running 'C-u g' to display the 514message in raw form before using '|' to run the pipe can work 515this problem around.