"Fossies" - the Fresh Open Source Software Archive

Member "git-2.31.1.windows.1/Documentation/SubmittingPatches" (27 Mar 2021, 23530 Bytes) of package /windows/misc/git-2.31.1.windows.1.zip:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the last Fossies "Diffs" side-by-side code changes report for "SubmittingPatches": 2.30.0_vs_2.30.1.

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