Merge branch 'pb/ggg-in-mfc-doc'
Documentation update. * pb/ggg-in-mfc-doc: MyFirstContribution: drop PR description for GGG single-patch contributions MyFirstContribution: reference "The cover letter" in GitGitGadget section MyFirstContribution: reference "The cover letter" in "Preparing Email" MyFirstContribution: add standalone section on cover letter MyFirstContribution: add "Anatomy of a Patch Series" section
This commit is contained in:
Junio C Hamano
commit
3ce9483c1a
@ -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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user