Documentation / SubmittingPatcheson commit Merge branch 'jk/fetch-prune-doc' into maint (1c22105)
   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
 124
 125(3) Generate your patch using Git tools out of your commits.
 126
 127Git based diff tools generate unidiff which is the preferred format.
 128
 129You do not have to be afraid to use -M option to "git diff" or
 130"git format-patch", if your patch involves file renames.  The
 131receiving end can handle them just fine.
 132
 133Please make sure your patch does not add commented out debugging code,
 134or include any extra files which do not relate to what your patch
 135is trying to achieve. Make sure to review
 136your patch after generating it, to ensure accuracy.  Before
 137sending out, please make sure it cleanly applies to the "master"
 138branch head.  If you are preparing a work based on "next" branch,
 139that is fine, but please mark it as such.
 140
 141
 142(4) Sending your patches.
 143
 144Learn to use format-patch and send-email if possible.  These commands
 145are optimized for the workflow of sending patches, avoiding many ways
 146your existing e-mail client that is optimized for "multipart/*" mime
 147type e-mails to corrupt and render your patches unusable.
 148
 149People on the Git mailing list need to be able to read and
 150comment on the changes you are submitting.  It is important for
 151a developer to be able to "quote" your changes, using standard
 152e-mail tools, so that they may comment on specific portions of
 153your code.  For this reason, each patch should be submitted
 154"inline" in a separate message.
 155
 156Multiple related patches should be grouped into their own e-mail
 157thread to help readers find all parts of the series.  To that end,
 158send them as replies to either an additional "cover letter" message
 159(see below), the first patch, or the respective preceding patch.
 160
 161If your log message (including your name on the
 162Signed-off-by line) is not writable in ASCII, make sure that
 163you send off a message in the correct encoding.
 164
 165WARNING: Be wary of your MUAs word-wrap
 166corrupting your patch.  Do not cut-n-paste your patch; you can
 167lose tabs that way if you are not careful.
 168
 169It is a common convention to prefix your subject line with
 170[PATCH].  This lets people easily distinguish patches from other
 171e-mail discussions.  Use of additional markers after PATCH and
 172the closing bracket to mark the nature of the patch is also
 173encouraged.  E.g. [PATCH/RFC] is often used when the patch is
 174not ready to be applied but it is for discussion, [PATCH v2],
 175[PATCH v3] etc. are often seen when you are sending an update to
 176what you have previously sent.
 177
 178"git format-patch" command follows the best current practice to
 179format the body of an e-mail message.  At the beginning of the
 180patch should come your commit message, ending with the
 181Signed-off-by: lines, and a line that consists of three dashes,
 182followed by the diffstat information and the patch itself.  If
 183you are forwarding a patch from somebody else, optionally, at
 184the beginning of the e-mail message just before the commit
 185message starts, you can put a "From: " line to name that person.
 186
 187You often want to add additional explanation about the patch,
 188other than the commit message itself.  Place such "cover letter"
 189material between the three-dash line and the diffstat.  For
 190patches requiring multiple iterations of review and discussion,
 191an explanation of changes between each iteration can be kept in
 192Git-notes and inserted automatically following the three-dash
 193line via `git format-patch --notes`.
 194
 195Do not attach the patch as a MIME attachment, compressed or not.
 196Do not let your e-mail client send quoted-printable.  Do not let
 197your e-mail client send format=flowed which would destroy
 198whitespaces in your patches. Many
 199popular e-mail applications will not always transmit a MIME
 200attachment as plain text, making it impossible to comment on
 201your code.  A MIME attachment also takes a bit more time to
 202process.  This does not decrease the likelihood of your
 203MIME-attached change being accepted, but it makes it more likely
 204that it will be postponed.
 205
 206Exception:  If your mailer is mangling patches then someone may ask
 207you to re-send them using MIME, that is OK.
 208
 209Do not PGP sign your patch, at least for now.  Most likely, your
 210maintainer or other people on the list would not have your PGP
 211key and would not bother obtaining it anyway.  Your patch is not
 212judged by who you are; a good patch from an unknown origin has a
 213far better chance of being accepted than a patch from a known,
 214respected origin that is done poorly or does incorrect things.
 215
 216If you really really really really want to do a PGP signed
 217patch, format it as "multipart/signed", not a text/plain message
 218that starts with '-----BEGIN PGP SIGNED MESSAGE-----'.  That is
 219not a text/plain, it's something else.
 220
 221Send your patch with "To:" set to the mailing list, with "cc:" listing
 222people who are involved in the area you are touching (the output from
 223"git blame $path" and "git shortlog --no-merges $path" would help to
 224identify them), to solicit comments and reviews.
 225
 226After the list reached a consensus that it is a good idea to apply the
 227patch, re-send it with "To:" set to the maintainer [*1*] and "cc:" the
 228list [*2*] for inclusion.
 229
 230Do not forget to add trailers such as "Acked-by:", "Reviewed-by:" and
 231"Tested-by:" lines as necessary to credit people who helped your
 232patch.
 233
 234    [Addresses]
 235     *1* The current maintainer: gitster@pobox.com
 236     *2* The mailing list: git@vger.kernel.org
 237
 238
 239(5) Sign your work
 240
 241To improve tracking of who did what, we've borrowed the
 242"sign-off" procedure from the Linux kernel project on patches
 243that are being emailed around.  Although core Git is a lot
 244smaller project it is a good discipline to follow it.
 245
 246The sign-off is a simple line at the end of the explanation for
 247the patch, which certifies that you wrote it or otherwise have
 248the right to pass it on as a open-source patch.  The rules are
 249pretty simple: if you can certify the below:
 250
 251        Developer's Certificate of Origin 1.1
 252
 253        By making a contribution to this project, I certify that:
 254
 255        (a) The contribution was created in whole or in part by me and I
 256            have the right to submit it under the open source license
 257            indicated in the file; or
 258
 259        (b) The contribution is based upon previous work that, to the best
 260            of my knowledge, is covered under an appropriate open source
 261            license and I have the right under that license to submit that
 262            work with modifications, whether created in whole or in part
 263            by me, under the same open source license (unless I am
 264            permitted to submit under a different license), as indicated
 265            in the file; or
 266
 267        (c) The contribution was provided directly to me by some other
 268            person who certified (a), (b) or (c) and I have not modified
 269            it.
 270
 271        (d) I understand and agree that this project and the contribution
 272            are public and that a record of the contribution (including all
 273            personal information I submit with it, including my sign-off) is
 274            maintained indefinitely and may be redistributed consistent with
 275            this project or the open source license(s) involved.
 276
 277then you just add a line saying
 278
 279        Signed-off-by: Random J Developer <random@developer.example.org>
 280
 281This line can be automatically added by Git if you run the git-commit
 282command with the -s option.
 283
 284Notice that you can place your own Signed-off-by: line when
 285forwarding somebody else's patch with the above rules for
 286D-C-O.  Indeed you are encouraged to do so.  Do not forget to
 287place an in-body "From: " line at the beginning to properly attribute
 288the change to its true author (see (2) above).
 289
 290Also notice that a real name is used in the Signed-off-by: line. Please
 291don't hide your real name.
 292
 293If you like, you can put extra tags at the end:
 294
 2951. "Reported-by:" is used to credit someone who found the bug that
 296   the patch attempts to fix.
 2972. "Acked-by:" says that the person who is more familiar with the area
 298   the patch attempts to modify liked the patch.
 2993. "Reviewed-by:", unlike the other tags, can only be offered by the
 300   reviewer and means that she is completely satisfied that the patch
 301   is ready for application.  It is usually offered only after a
 302   detailed review.
 3034. "Tested-by:" is used to indicate that the person applied the patch
 304   and found it to have the desired effect.
 305
 306You can also create your own tag or use one that's in common usage
 307such as "Thanks-to:", "Based-on-patch-by:", or "Mentored-by:".
 308
 309------------------------------------------------
 310Subsystems with dedicated maintainers
 311
 312Some parts of the system have dedicated maintainers with their own
 313repositories.
 314
 315 - git-gui/ comes from git-gui project, maintained by Pat Thoyts:
 316
 317        git://repo.or.cz/git-gui.git
 318
 319 - gitk-git/ comes from Paul Mackerras's gitk project:
 320
 321        git://ozlabs.org/~paulus/gitk
 322
 323 - po/ comes from the localization coordinator, Jiang Xin:
 324
 325        https://github.com/git-l10n/git-po/
 326
 327Patches to these parts should be based on their trees.
 328
 329------------------------------------------------
 330An ideal patch flow
 331
 332Here is an ideal patch flow for this project the current maintainer
 333suggests to the contributors:
 334
 335 (0) You come up with an itch.  You code it up.
 336
 337 (1) Send it to the list and cc people who may need to know about
 338     the change.
 339
 340     The people who may need to know are the ones whose code you
 341     are butchering.  These people happen to be the ones who are
 342     most likely to be knowledgeable enough to help you, but
 343     they have no obligation to help you (i.e. you ask for help,
 344     don't demand).  "git log -p -- $area_you_are_modifying" would
 345     help you find out who they are.
 346
 347 (2) You get comments and suggestions for improvements.  You may
 348     even get them in a "on top of your change" patch form.
 349
 350 (3) Polish, refine, and re-send to the list and the people who
 351     spend their time to improve your patch.  Go back to step (2).
 352
 353 (4) The list forms consensus that the last round of your patch is
 354     good.  Send it to the maintainer and cc the list.
 355
 356 (5) A topic branch is created with the patch and is merged to 'next',
 357     and cooked further and eventually graduates to 'master'.
 358
 359In any time between the (2)-(3) cycle, the maintainer may pick it up
 360from the list and queue it to 'pu', in order to make it easier for
 361people play with it without having to pick up and apply the patch to
 362their trees themselves.
 363
 364------------------------------------------------
 365Know the status of your patch after submission
 366
 367* You can use Git itself to find out when your patch is merged in
 368  master. 'git pull --rebase' will automatically skip already-applied
 369  patches, and will let you know. This works only if you rebase on top
 370  of the branch in which your patch has been merged (i.e. it will not
 371  tell you if your patch is merged in pu if you rebase on top of
 372  master).
 373
 374* Read the Git mailing list, the maintainer regularly posts messages
 375  entitled "What's cooking in git.git" and "What's in git.git" giving
 376  the status of various proposed changes.
 377
 378--------------------------------------------------
 379GitHub-Travis CI hints
 380
 381With an account at GitHub (you can get one for free to work on open
 382source projects), you can use Travis CI to test your changes on Linux,
 383Mac (and hopefully soon Windows).  You can find a successful example
 384test build here: https://travis-ci.org/git/git/builds/120473209
 385
 386Follow these steps for the initial setup:
 387
 388 (1) Fork https://github.com/git/git to your GitHub account.
 389     You can find detailed instructions how to fork here:
 390     https://help.github.com/articles/fork-a-repo/
 391
 392 (2) Open the Travis CI website: https://travis-ci.org
 393
 394 (3) Press the "Sign in with GitHub" button.
 395
 396 (4) Grant Travis CI permissions to access your GitHub account.
 397     You can find more information about the required permissions here:
 398     https://docs.travis-ci.com/user/github-oauth-scopes
 399
 400 (5) Open your Travis CI profile page: https://travis-ci.org/profile
 401
 402 (6) Enable Travis CI builds for your Git fork.
 403
 404After the initial setup, Travis CI will run whenever you push new changes
 405to your fork of Git on GitHub.  You can monitor the test state of all your
 406branches here: https://travis-ci.org/<Your GitHub handle>/git/branches
 407
 408If a branch did not pass all test cases then it is marked with a red
 409cross.  In that case you can click on the failing Travis CI job and
 410scroll all the way down in the log.  Find the line "<-- Click here to see
 411detailed test output!" and click on the triangle next to the log line
 412number to expand the detailed test output.  Here is such a failing
 413example: https://travis-ci.org/git/git/jobs/122676187
 414
 415Fix the problem and push your fix to your Git fork.  This will trigger
 416a new Travis CI build to ensure all tests pass.
 417
 418
 419------------------------------------------------
 420MUA specific hints
 421
 422Some of patches I receive or pick up from the list share common
 423patterns of breakage.  Please make sure your MUA is set up
 424properly not to corrupt whitespaces.
 425
 426See the DISCUSSION section of git-format-patch(1) for hints on
 427checking your patch by mailing it to yourself and applying with
 428git-am(1).
 429
 430While you are at it, check the resulting commit log message from
 431a trial run of applying the patch.  If what is in the resulting
 432commit is not exactly what you would want to see, it is very
 433likely that your maintainer would end up hand editing the log
 434message when he applies your patch.  Things like "Hi, this is my
 435first patch.\n", if you really want to put in the patch e-mail,
 436should come after the three-dash line that signals the end of the
 437commit message.
 438
 439
 440Pine
 441----
 442
 443(Johannes Schindelin)
 444
 445I don't know how many people still use pine, but for those poor
 446souls it may be good to mention that the quell-flowed-text is
 447needed for recent versions.
 448
 449... the "no-strip-whitespace-before-send" option, too. AFAIK it
 450was introduced in 4.60.
 451
 452(Linus Torvalds)
 453
 454And 4.58 needs at least this.
 455
 456---
 457diff-tree 8326dd8350be64ac7fc805f6563a1d61ad10d32c (from e886a61f76edf5410573e92e38ce22974f9c40f1)
 458Author: Linus Torvalds <torvalds@g5.osdl.org>
 459Date:   Mon Aug 15 17:23:51 2005 -0700
 460
 461    Fix pine whitespace-corruption bug
 462
 463    There's no excuse for unconditionally removing whitespace from
 464    the pico buffers on close.
 465
 466diff --git a/pico/pico.c b/pico/pico.c
 467--- a/pico/pico.c
 468+++ b/pico/pico.c
 469@@ -219,7 +219,9 @@ PICO *pm;
 470            switch(pico_all_done){      /* prepare for/handle final events */
 471              case COMP_EXIT :          /* already confirmed */
 472                packheader();
 473+#if 0
 474                stripwhitespace();
 475+#endif
 476                c |= COMP_EXIT;
 477                break;
 478
 479
 480(Daniel Barkalow)
 481
 482> A patch to SubmittingPatches, MUA specific help section for
 483> users of Pine 4.63 would be very much appreciated.
 484
 485Ah, it looks like a recent version changed the default behavior to do the
 486right thing, and inverted the sense of the configuration option. (Either
 487that or Gentoo did it.) So you need to set the
 488"no-strip-whitespace-before-send" option, unless the option you have is
 489"strip-whitespace-before-send", in which case you should avoid checking
 490it.
 491
 492
 493Thunderbird, KMail, GMail
 494-------------------------
 495
 496See the MUA-SPECIFIC HINTS section of git-format-patch(1).
 497
 498Gnus
 499----
 500
 501'|' in the *Summary* buffer can be used to pipe the current
 502message to an external program, and this is a handy way to drive
 503"git am".  However, if the message is MIME encoded, what is
 504piped into the program is the representation you see in your
 505*Article* buffer after unwrapping MIME.  This is often not what
 506you would want for two reasons.  It tends to screw up non ASCII
 507characters (most notably in people's names), and also
 508whitespaces (fatal in patches).  Running 'C-u g' to display the
 509message in raw form before using '|' to run the pipe can work
 510this problem around.