diff options
Diffstat (limited to 'Documentation/MyFirstContribution.txt')
| -rw-r--r-- | Documentation/MyFirstContribution.txt | 155 |
1 files changed, 120 insertions, 35 deletions
diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt index 63a2ef5..1da15d9 100644 --- a/Documentation/MyFirstContribution.txt +++ b/Documentation/MyFirstContribution.txt @@ -710,13 +710,104 @@ dependencies. `prove` also makes the output nicer. Go ahead and commit this change, as well. [[ready-to-share]] -== Getting Ready to Share +== Getting Ready to Share: Anatomy of a Patch Series You may have noticed already that the Git project performs its code reviews via emailed patches, which are then applied by the maintainer when they are ready -and approved by the community. The Git project does not accept patches from +and approved by the community. The Git project does not accept contributions from pull requests, and the patches emailed for review need to be formatted a -specific way. At this point the tutorial diverges, in order to demonstrate two +specific way. + +:patch-series: https://lore.kernel.org/git/pull.1218.git.git.1645209647.gitgitgadget@gmail.com/ +:lore: https://lore.kernel.org/git/ + +Before taking a look at how to convert your commits into emailed patches, +let's analyze what the end result, a "patch series", looks like. Here is an +{patch-series}[example] of the summary view for a patch series on the web interface of +the {lore}[Git mailing list archive]: + +---- +2022-02-18 18:40 [PATCH 0/3] libify reflog John Cai via GitGitGadget +2022-02-18 18:40 ` [PATCH 1/3] reflog: libify delete reflog function and helpers John Cai via GitGitGadget +2022-02-18 19:10 ` Ævar Arnfjörð Bjarmason [this message] +2022-02-18 19:39 ` Taylor Blau +2022-02-18 19:48 ` Ævar Arnfjörð Bjarmason +2022-02-18 19:35 ` Taylor Blau +2022-02-21 1:43 ` John Cai +2022-02-21 1:50 ` Taylor Blau +2022-02-23 19:50 ` John Cai +2022-02-18 20:00 ` // other replies ellided +2022-02-18 18:40 ` [PATCH 2/3] reflog: call reflog_delete from reflog.c John Cai via GitGitGadget +2022-02-18 19:15 ` Ævar Arnfjörð Bjarmason +2022-02-18 20:26 ` Junio C Hamano +2022-02-18 18:40 ` [PATCH 3/3] stash: call reflog_delete from reflog.c John Cai via GitGitGadget +2022-02-18 19:20 ` Ævar Arnfjörð Bjarmason +2022-02-19 0:21 ` Taylor Blau +2022-02-22 2:36 ` John Cai +2022-02-22 10:51 ` Ævar Arnfjörð Bjarmason +2022-02-18 19:29 ` [PATCH 0/3] libify reflog Ævar Arnfjörð Bjarmason +2022-02-22 18:30 ` [PATCH v2 0/3] libify reflog John Cai via GitGitGadget +2022-02-22 18:30 ` [PATCH v2 1/3] stash: add test to ensure reflog --rewrite --updatref behavior John Cai via GitGitGadget +2022-02-23 8:54 ` Ævar Arnfjörð Bjarmason +2022-02-23 21:27 ` Junio C Hamano +// continued +---- + +We can note a few things: + +- Each commit is sent as a separate email, with the commit message title as + subject, prefixed with "[PATCH _i_/_n_]" for the _i_-th commit of an + _n_-commit series. +- Each patch is sent as a reply to an introductory email called the _cover + letter_ of the series, prefixed "[PATCH 0/_n_]". +- Subsequent iterations of the patch series are labelled "PATCH v2", "PATCH + v3", etc. in place of "PATCH". For example, "[PATCH v2 1/3]" would be the first of + three patches in the second iteration. Each iteration is sent with a new cover + letter (like "[PATCH v2 0/3]" above), itself a reply to the cover letter of the + previous iteration (more on that below). + +NOTE: A single-patch topic is sent with "[PATCH]", "[PATCH v2]", etc. without +_i_/_n_ numbering (in the above thread overview, no single-patch topic appears, +though). + +[[cover-letter]] +=== The cover letter + +In addition to an email per patch, the Git community also expects your patches +to come with a cover letter. This is an important component of change +submission as it explains to the community from a high level what you're trying +to do, and why, in a way that's more apparent than just looking at your +patches. + +The title of your cover letter should be something which succinctly covers the +purpose of your entire topic branch. It's often in the imperative mood, just +like our commit message titles. Here is how we'll title our series: + +--- +Add the 'psuh' command +--- + +The body of the cover letter is used to give additional context to reviewers. +Be sure to explain anything your patches don't make clear on their own, but +remember that since the cover letter is not recorded in the commit history, +anything that might be useful to future readers of the repository's history +should also be in your commit messages. + +Here's an example body for `psuh`: + +---- +Our internal metrics indicate widespread interest in the command +git-psuh - that is, many users are trying to use it, but finding it is +unavailable, using some unknown workaround instead. + +The following handful of patches add the psuh command and implement some +handy features on top of it. + +This patchset is part of the MyFirstContribution tutorial and should not +be merged. +---- + +At this point the tutorial diverges, in order to demonstrate two different methods of formatting your patchset and getting it reviewed. The first method to be covered is GitGitGadget, which is useful for those @@ -808,8 +899,22 @@ https://github.com/gitgitgadget/git and open a PR either with the "New pull request" button or the convenient "Compare & pull request" button that may appear with the name of your newly pushed branch. -Review the PR's title and description, as it's used by GitGitGadget as the cover -letter for your change. When you're happy, submit your pull request. +Review the PR's title and description, as they're used by GitGitGadget +respectively as the subject and body of the cover letter for your change. Refer +to <<cover-letter,"The cover letter">> above for advice on how to title your +submission and what content to include in the description. + +NOTE: For single-patch contributions, your commit message should already be +meaningful and explain at a high level the purpose (what is happening and why) +of your patch, so you usually do not need any additional context. In that case, +remove the PR description that GitHub automatically generates from your commit +message (your PR description should be empty). If you do need to supply even +more context, you can do so in that space and it will be appended to the email +that GitGitGadget will send, between the three-dash line and the diffstat +(see <<single-patch,Bonus Chapter: One-Patch Changes>> for how this looks once +submitted). + +When you're happy, submit your pull request. [[run-ci-ggg]] === Running CI and Getting Ready to Send @@ -952,49 +1057,29 @@ but want reviewers to look at what they have so far. You can add this flag with Check and make sure that your patches and cover letter template exist in the directory you specified - you're nearly ready to send out your review! -[[cover-letter]] +[[preparing-cover-letter]] === Preparing Email -In addition to an email per patch, the Git community also expects your patches -to come with a cover letter, typically with a subject line [PATCH 0/x] (where -x is the number of patches you're sending). Since you invoked `format-patch` -with `--cover-letter`, you've already got a template ready. Open it up in your -favorite editor. +Since you invoked `format-patch` with `--cover-letter`, you've already got a +cover letter template ready. Open it up in your favorite editor. You should see a number of headers present already. Check that your `From:` -header is correct. Then modify your `Subject:` to something which succinctly -covers the purpose of your entire topic branch, for example: +header is correct. Then modify your `Subject:` (see <<cover-letter,above>> for +how to choose good title for your patch series): ---- -Subject: [PATCH 0/7] adding the 'psuh' command +Subject: [PATCH 0/7] Add the 'psuh' command ---- Make sure you retain the ``[PATCH 0/X]'' part; that's what indicates to the Git -community that this email is the beginning of a review, and many reviewers -filter their email for this type of flag. +community that this email is the beginning of a patch series, and many +reviewers filter their email for this type of flag. You'll need to add some extra parameters when you invoke `git send-email` to add the cover letter. -Next you'll have to fill out the body of your cover letter. This is an important -component of change submission as it explains to the community from a high level -what you're trying to do, and why, in a way that's more apparent than just -looking at your diff. Be sure to explain anything your diff doesn't make clear -on its own. - -Here's an example body for `psuh`: - ----- -Our internal metrics indicate widespread interest in the command -git-psuh - that is, many users are trying to use it, but finding it is -unavailable, using some unknown workaround instead. - -The following handful of patches add the psuh command and implement some -handy features on top of it. - -This patchset is part of the MyFirstContribution tutorial and should not -be merged. ----- +Next you'll have to fill out the body of your cover letter. Again, see +<<cover-letter,above>> for what content to include. The template created by `git format-patch --cover-letter` includes a diffstat. This gives reviewers a summary of what they're in for when reviewing your topic. |