Skip to content

Commit

Permalink
Merge branch 'pb/ggg-in-mfc-doc'
Browse files Browse the repository at this point in the history 
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
  • Loading branch information
@gitster
gitster committed May 25, 2022
2 parents 9cf4e0c + 4ec5008 commit 3ce9483
Showing 1 changed file with 120 additions and 35 deletions.
155 changes: 120 additions & 35 deletions Documentation/MyFirstContribution.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down

0 comments on commit 3ce9483

Please sign in to comment.