about summary refs log tree commit diff
path: root/third_party/git/Documentation/SubmittingPatches
diff options
context:
space:
mode:
Diffstat (limited to 'third_party/git/Documentation/SubmittingPatches')
-rw-r--r--third_party/git/Documentation/SubmittingPatches576
1 files changed, 0 insertions, 576 deletions
diff --git a/third_party/git/Documentation/SubmittingPatches b/third_party/git/Documentation/SubmittingPatches
deleted file mode 100644
index 291b61e26213..000000000000
--- a/third_party/git/Documentation/SubmittingPatches
+++ /dev/null
@@ -1,576 +0,0 @@
-Submitting Patches
-==================
-
-== Guidelines
-
-Here are some guidelines for people who want to contribute their code to this
-software. There is also a link:MyFirstContribution.html[step-by-step tutorial]
-available which covers many of these same guidelines.
-
-[[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 `seen`, 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 `seen` 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..seen` 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 hash (subject, date)", 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 (with the subject enclosed in a pair of double-quotes), or this
-invocation of `git show`:
-
-....
-	git show -s --pretty=reference <commit>
-....
-
-or, on an older version of Git without support for --pretty=reference:
-
-....
-	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 Pratyush Yadav:
-
-	https://github.com/prati0100/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 `seen`, 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 `seen` 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.