diff options
Diffstat (limited to 'third_party/git/Documentation/SubmittingPatches')
| -rw-r--r-- | third_party/git/Documentation/SubmittingPatches | 569 |
1 files changed, 0 insertions, 569 deletions
diff --git a/third_party/git/Documentation/SubmittingPatches b/third_party/git/Documentation/SubmittingPatches deleted file mode 100644 index 6d589e118c..0000000000 --- a/third_party/git/Documentation/SubmittingPatches +++ /dev/null @@ -1,569 +0,0 @@ -Submitting Patches -================== - -== Guidelines - -Here are some guidelines for people who want to contribute their code -to this software. - -[[base-branch]] -=== Decide what to base your work on. - -In general, always base your work on the oldest branch that your -change is relevant to. - -* A bugfix should be based on `maint` in general. If the bug is not - present in `maint`, base it on `master`. For a bug that's not yet - in `master`, find the topic that introduces the regression, and - base your work on the tip of the topic. - -* A new feature should be based on `master` in general. If the new - feature depends on a topic that is in `pu`, but not in `master`, - base your work on the tip of that topic. - -* Corrections and enhancements to a topic not yet in `master` should - be based on the tip of that topic. If the topic has not been merged - to `next`, it's alright to add a note to squash minor corrections - into the series. - -* In the exceptional case that a new feature depends on several topics - not in `master`, start working on `next` or `pu` privately and send - out patches for discussion. Before the final merge, you may have to - wait until some of the dependent topics graduate to `master`, and - rebase your work. - -* Some parts of the system have dedicated maintainers with their own - repositories (see the section "Subsystems" below). Changes to - these parts should be based on their trees. - -To find the tip of a topic branch, run `git log --first-parent -master..pu` and look for the merge commit. The second parent of this -commit is the tip of the topic branch. - -[[separate-commits]] -=== Make separate commits for logically separate changes. - -Unless your patch is really trivial, you should not be sending -out a patch that was generated between your working tree and -your commit head. Instead, always make a commit with complete -commit message and generate a series of patches from your -repository. It is a good discipline. - -Give an explanation for the change(s) that is detailed enough so -that people can judge if it is good thing to do, without reading -the actual patch text to determine how well the code does what -the explanation promises to do. - -If your description starts to get too long, that's a sign that you -probably need to split up your commit to finer grained pieces. -That being said, patches which plainly describe the things that -help reviewers check the patch, and future maintainers understand -the code, are the most beautiful patches. Descriptions that summarize -the point in the subject well, and describe the motivation for the -change, the approach taken by the change, and if relevant how this -differs substantially from the prior version, are all good things -to have. - -Make sure that you have tests for the bug you are fixing. See -`t/README` for guidance. - -[[tests]] -When adding a new feature, make sure that you have new tests to show -the feature triggers the new behavior when it should, and to show the -feature does not trigger when it shouldn't. After any code change, make -sure that the entire test suite passes. - -If you have an account at GitHub (and you can get one for free to work -on open source projects), you can use their Travis CI integration to -test your changes on Linux, Mac (and hopefully soon Windows). See -GitHub-Travis CI hints section for details. - -Do not forget to update the documentation to describe the updated -behavior and make sure that the resulting documentation set formats -well (try the Documentation/doc-diff script). - -We currently have a liberal mixture of US and UK English norms for -spelling and grammar, which is somewhat unfortunate. A huge patch that -touches the files all over the place only to correct the inconsistency -is not welcome, though. Potential clashes with other changes that can -result from such a patch are not worth it. We prefer to gradually -reconcile the inconsistencies in favor of US English, with small and -easily digestible patches, as a side effect of doing some other real -work in the vicinity (e.g. rewriting a paragraph for clarity, while -turning en_UK spelling to en_US). Obvious typographical fixes are much -more welcomed ("teh -> "the"), preferably submitted as independent -patches separate from other documentation changes. - -[[whitespace-check]] -Oh, another thing. We are picky about whitespaces. Make sure your -changes do not trigger errors with the sample pre-commit hook shipped -in `templates/hooks--pre-commit`. To help ensure this does not happen, -run `git diff --check` on your changes before you commit. - -[[describe-changes]] -=== Describe your changes well. - -The first line of the commit message should be a short description (50 -characters is the soft limit, see DISCUSSION in linkgit:git-commit[1]), -and should skip the full stop. It is also conventional in most cases to -prefix the first line with "area: " where the area is a filename or -identifier for the general area of the code being modified, e.g. - -* doc: clarify distinction between sign-off and pgp-signing -* githooks.txt: improve the intro section - -If in doubt which identifier to use, run `git log --no-merges` on the -files you are modifying to see the current conventions. - -[[summary-section]] -It's customary to start the remainder of the first line after "area: " -with a lower-case letter. E.g. "doc: clarify...", not "doc: -Clarify...", or "githooks.txt: improve...", not "githooks.txt: -Improve...". - -[[meaningful-message]] -The body should provide a meaningful commit message, which: - -. explains the problem the change tries to solve, i.e. what is wrong - with the current code without the change. - -. justifies the way the change solves the problem, i.e. why the - result with the change is better. - -. alternate solutions considered but discarded, if any. - -[[imperative-mood]] -Describe your changes in imperative mood, e.g. "make xyzzy do frotz" -instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy -to do frotz", as if you are giving orders to the codebase to change -its behavior. Try to make sure your explanation can be understood -without external resources. Instead of giving a URL to a mailing list -archive, summarize the relevant points of the discussion. - -[[commit-reference]] -If you want to reference a previous commit in the history of a stable -branch, use the format "abbreviated sha1 (subject, date)", -with the subject enclosed in a pair of double-quotes, like this: - -.... - Commit f86a374 ("pack-bitmap.c: fix a memleak", 2015-03-30) - noticed that ... -.... - -The "Copy commit summary" command of gitk can be used to obtain this -format, or this invocation of `git show`: - -.... - git show -s --date=short --pretty='format:%h ("%s", %ad)' <commit> -.... - -[[git-tools]] -=== Generate your patch using Git tools out of your commits. - -Git based diff tools generate unidiff which is the preferred format. - -You do not have to be afraid to use `-M` option to `git diff` or -`git format-patch`, if your patch involves file renames. The -receiving end can handle them just fine. - -[[review-patch]] -Please make sure your patch does not add commented out debugging code, -or include any extra files which do not relate to what your patch -is trying to achieve. Make sure to review -your patch after generating it, to ensure accuracy. Before -sending out, please make sure it cleanly applies to the `master` -branch head. If you are preparing a work based on "next" branch, -that is fine, but please mark it as such. - -[[send-patches]] -=== Sending your patches. - -:security-ml: footnoteref:[security-ml,The Git Security mailing list: git-security@googlegroups.com] - -Before sending any patches, please note that patches that may be -security relevant should be submitted privately to the Git Security -mailing list{security-ml}, instead of the public mailing list. - -Learn to use format-patch and send-email if possible. These commands -are optimized for the workflow of sending patches, avoiding many ways -your existing e-mail client that is optimized for "multipart/*" mime -type e-mails to corrupt and render your patches unusable. - -People on the Git mailing list need to be able to read and -comment on the changes you are submitting. It is important for -a developer to be able to "quote" your changes, using standard -e-mail tools, so that they may comment on specific portions of -your code. For this reason, each patch should be submitted -"inline" in a separate message. - -Multiple related patches should be grouped into their own e-mail -thread to help readers find all parts of the series. To that end, -send them as replies to either an additional "cover letter" message -(see below), the first patch, or the respective preceding patch. - -If your log message (including your name on the -Signed-off-by line) is not writable in ASCII, make sure that -you send off a message in the correct encoding. - -WARNING: Be wary of your MUAs word-wrap -corrupting your patch. Do not cut-n-paste your patch; you can -lose tabs that way if you are not careful. - -It is a common convention to prefix your subject line with -[PATCH]. This lets people easily distinguish patches from other -e-mail discussions. Use of markers in addition to PATCH within -the brackets to describe the nature of the patch is also -encouraged. E.g. [RFC PATCH] (where RFC stands for "request for -comments") is often used to indicate a patch needs further -discussion before being accepted, [PATCH v2], [PATCH v3] etc. -are often seen when you are sending an update to what you have -previously sent. - -The `git format-patch` command follows the best current practice to -format the body of an e-mail message. At the beginning of the -patch should come your commit message, ending with the -Signed-off-by: lines, and a line that consists of three dashes, -followed by the diffstat information and the patch itself. If -you are forwarding a patch from somebody else, optionally, at -the beginning of the e-mail message just before the commit -message starts, you can put a "From: " line to name that person. -To change the default "[PATCH]" in the subject to "[<text>]", use -`git format-patch --subject-prefix=<text>`. As a shortcut, you -can use `--rfc` instead of `--subject-prefix="RFC PATCH"`, or -`-v <n>` instead of `--subject-prefix="PATCH v<n>"`. - -You often want to add additional explanation about the patch, -other than the commit message itself. Place such "cover letter" -material between the three-dash line and the diffstat. For -patches requiring multiple iterations of review and discussion, -an explanation of changes between each iteration can be kept in -Git-notes and inserted automatically following the three-dash -line via `git format-patch --notes`. - -[[attachment]] -Do not attach the patch as a MIME attachment, compressed or not. -Do not let your e-mail client send quoted-printable. Do not let -your e-mail client send format=flowed which would destroy -whitespaces in your patches. Many -popular e-mail applications will not always transmit a MIME -attachment as plain text, making it impossible to comment on -your code. A MIME attachment also takes a bit more time to -process. This does not decrease the likelihood of your -MIME-attached change being accepted, but it makes it more likely -that it will be postponed. - -Exception: If your mailer is mangling patches then someone may ask -you to re-send them using MIME, that is OK. - -[[pgp-signature]] -Do not PGP sign your patch. Most likely, your maintainer or other people on the -list would not have your PGP key and would not bother obtaining it anyway. -Your patch is not judged by who you are; a good patch from an unknown origin -has a far better chance of being accepted than a patch from a known, respected -origin that is done poorly or does incorrect things. - -If you really really really really want to do a PGP signed -patch, format it as "multipart/signed", not a text/plain message -that starts with `-----BEGIN PGP SIGNED MESSAGE-----`. That is -not a text/plain, it's something else. - -:security-ml-ref: footnoteref:[security-ml] - -As mentioned at the beginning of the section, patches that may be -security relevant should not be submitted to the public mailing list -mentioned below, but should instead be sent privately to the Git -Security mailing list{security-ml-ref}. - -Send your patch with "To:" set to the mailing list, with "cc:" listing -people who are involved in the area you are touching (the `git -contacts` command in `contrib/contacts/` can help to -identify them), to solicit comments and reviews. - -:current-maintainer: footnote:[The current maintainer: gitster@pobox.com] -:git-ml: footnote:[The mailing list: git@vger.kernel.org] - -After the list reached a consensus that it is a good idea to apply the -patch, re-send it with "To:" set to the maintainer{current-maintainer} and "cc:" the -list{git-ml} for inclusion. - -Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and -`Tested-by:` lines as necessary to credit people who helped your -patch. - -[[sign-off]] -=== Certify your work by adding your "Signed-off-by: " line - -To improve tracking of who did what, we've borrowed the -"sign-off" procedure from the Linux kernel project on patches -that are being emailed around. Although core Git is a lot -smaller project it is a good discipline to follow it. - -The sign-off is a simple line at the end of the explanation for -the patch, which certifies that you wrote it or otherwise have -the right to pass it on as an open-source patch. The rules are -pretty simple: if you can certify the below D-C-O: - -[[dco]] -.Developer's Certificate of Origin 1.1 -____ -By making a contribution to this project, I certify that: - -a. The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - -b. The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or - -c. The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - -d. I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. -____ - -then you just add a line saying - -.... - Signed-off-by: Random J Developer <random@developer.example.org> -.... - -This line can be automatically added by Git if you run the git-commit -command with the -s option. - -Notice that you can place your own Signed-off-by: line when -forwarding somebody else's patch with the above rules for -D-C-O. Indeed you are encouraged to do so. Do not forget to -place an in-body "From: " line at the beginning to properly attribute -the change to its true author (see (2) above). - -[[real-name]] -Also notice that a real name is used in the Signed-off-by: line. Please -don't hide your real name. - -[[commit-trailers]] -If you like, you can put extra tags at the end: - -. `Reported-by:` is used to credit someone who found the bug that - the patch attempts to fix. -. `Acked-by:` says that the person who is more familiar with the area - the patch attempts to modify liked the patch. -. `Reviewed-by:`, unlike the other tags, can only be offered by the - reviewer and means that she is completely satisfied that the patch - is ready for application. It is usually offered only after a - detailed review. -. `Tested-by:` is used to indicate that the person applied the patch - and found it to have the desired effect. - -You can also create your own tag or use one that's in common usage -such as "Thanks-to:", "Based-on-patch-by:", or "Mentored-by:". - -== Subsystems with dedicated maintainers - -Some parts of the system have dedicated maintainers with their own -repositories. - -- `git-gui/` comes from git-gui project, maintained by Pat Thoyts: - - git://repo.or.cz/git-gui.git - -- `gitk-git/` comes from Paul Mackerras's gitk project: - - git://ozlabs.org/~paulus/gitk - -- `po/` comes from the localization coordinator, Jiang Xin: - - https://github.com/git-l10n/git-po/ - -Patches to these parts should be based on their trees. - -[[patch-flow]] -== An ideal patch flow - -Here is an ideal patch flow for this project the current maintainer -suggests to the contributors: - -. You come up with an itch. You code it up. - -. Send it to the list and cc people who may need to know about - the change. -+ -The people who may need to know are the ones whose code you -are butchering. These people happen to be the ones who are -most likely to be knowledgeable enough to help you, but -they have no obligation to help you (i.e. you ask for help, -don't demand). +git log -p {litdd} _$area_you_are_modifying_+ would -help you find out who they are. - -. You get comments and suggestions for improvements. You may - even get them in an "on top of your change" patch form. - -. Polish, refine, and re-send to the list and the people who - spend their time to improve your patch. Go back to step (2). - -. The list forms consensus that the last round of your patch is - good. Send it to the maintainer and cc the list. - -. A topic branch is created with the patch and is merged to `next`, - and cooked further and eventually graduates to `master`. - -In any time between the (2)-(3) cycle, the maintainer may pick it up -from the list and queue it to `pu`, in order to make it easier for -people play with it without having to pick up and apply the patch to -their trees themselves. - -[[patch-status]] -== Know the status of your patch after submission - -* You can use Git itself to find out when your patch is merged in - master. `git pull --rebase` will automatically skip already-applied - patches, and will let you know. This works only if you rebase on top - of the branch in which your patch has been merged (i.e. it will not - tell you if your patch is merged in pu if you rebase on top of - master). - -* Read the Git mailing list, the maintainer regularly posts messages - entitled "What's cooking in git.git" and "What's in git.git" giving - the status of various proposed changes. - -[[travis]] -== GitHub-Travis CI hints - -With an account at GitHub (you can get one for free to work on open -source projects), you can use Travis CI to test your changes on Linux, -Mac (and hopefully soon Windows). You can find a successful example -test build here: https://travis-ci.org/git/git/builds/120473209 - -Follow these steps for the initial setup: - -. Fork https://github.com/git/git to your GitHub account. - You can find detailed instructions how to fork here: - https://help.github.com/articles/fork-a-repo/ - -. Open the Travis CI website: https://travis-ci.org - -. Press the "Sign in with GitHub" button. - -. Grant Travis CI permissions to access your GitHub account. - You can find more information about the required permissions here: - https://docs.travis-ci.com/user/github-oauth-scopes - -. Open your Travis CI profile page: https://travis-ci.org/profile - -. Enable Travis CI builds for your Git fork. - -After the initial setup, Travis CI will run whenever you push new changes -to your fork of Git on GitHub. You can monitor the test state of all your -branches here: https://travis-ci.org/__<Your GitHub handle>__/git/branches - -If a branch did not pass all test cases then it is marked with a red -cross. In that case you can click on the failing Travis CI job and -scroll all the way down in the log. Find the line "<-- Click here to see -detailed test output!" and click on the triangle next to the log line -number to expand the detailed test output. Here is such a failing -example: https://travis-ci.org/git/git/jobs/122676187 - -Fix the problem and push your fix to your Git fork. This will trigger -a new Travis CI build to ensure all tests pass. - -[[mua]] -== MUA specific hints - -Some of patches I receive or pick up from the list share common -patterns of breakage. Please make sure your MUA is set up -properly not to corrupt whitespaces. - -See the DISCUSSION section of linkgit:git-format-patch[1] for hints on -checking your patch by mailing it to yourself and applying with -linkgit:git-am[1]. - -While you are at it, check the resulting commit log message from -a trial run of applying the patch. If what is in the resulting -commit is not exactly what you would want to see, it is very -likely that your maintainer would end up hand editing the log -message when he applies your patch. Things like "Hi, this is my -first patch.\n", if you really want to put in the patch e-mail, -should come after the three-dash line that signals the end of the -commit message. - - -=== Pine - -(Johannes Schindelin) - -.... -I don't know how many people still use pine, but for those poor -souls it may be good to mention that the quell-flowed-text is -needed for recent versions. - -... the "no-strip-whitespace-before-send" option, too. AFAIK it -was introduced in 4.60. -.... - -(Linus Torvalds) - -.... -And 4.58 needs at least this. - -diff-tree 8326dd8350be64ac7fc805f6563a1d61ad10d32c (from e886a61f76edf5410573e92e38ce22974f9c40f1) -Author: Linus Torvalds <torvalds@g5.osdl.org> -Date: Mon Aug 15 17:23:51 2005 -0700 - - Fix pine whitespace-corruption bug - - There's no excuse for unconditionally removing whitespace from - the pico buffers on close. - -diff --git a/pico/pico.c b/pico/pico.c ---- a/pico/pico.c -+++ b/pico/pico.c -@@ -219,7 +219,9 @@ PICO *pm; - switch(pico_all_done){ /* prepare for/handle final events */ - case COMP_EXIT : /* already confirmed */ - packheader(); -+#if 0 - stripwhitespace(); -+#endif - c |= COMP_EXIT; - break; -.... - -(Daniel Barkalow) - -.... -> A patch to SubmittingPatches, MUA specific help section for -> users of Pine 4.63 would be very much appreciated. - -Ah, it looks like a recent version changed the default behavior to do the -right thing, and inverted the sense of the configuration option. (Either -that or Gentoo did it.) So you need to set the -"no-strip-whitespace-before-send" option, unless the option you have is -"strip-whitespace-before-send", in which case you should avoid checking -it. -.... - -=== Thunderbird, KMail, GMail - -See the MUA-SPECIFIC HINTS section of linkgit:git-format-patch[1]. - -=== Gnus - -"|" in the `*Summary*` buffer can be used to pipe the current -message to an external program, and this is a handy way to drive -`git am`. However, if the message is MIME encoded, what is -piped into the program is the representation you see in your -`*Article*` buffer after unwrapping MIME. This is often not what -you would want for two reasons. It tends to screw up non ASCII -characters (most notably in people's names), and also -whitespaces (fatal in patches). Running "C-u g" to display the -message in raw form before using "|" to run the pipe can work -this problem around. |