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