[v3,1/5] MyFirstContribution: add "Anatomy of a Patch Series" section

Commit Message

Philippe Blain May 12, 2022, 11:43 p.m. UTC

From: Philippe Blain <[e-mail]>

Before describing how to send patches to the mailing list either with
GitGitGadget or 'git send-email', the MyFirstContribution tutorial
includes a small "Getting Ready to Share" section where the two
different methods are briefly introduced.

Use this section to also describe what a patch series looks like once
submitted, so that readers get an understanding of the end result before
diving into how to accomplish that end result.

Start by copying the "thread overview" section of a recent contribution
from the public-inbox web UI and explaining how each commit is a
separate mail, and point out the cover letter.

Subsequent commits will move the existing description of the purpose of
the cover letter from the 'git send-email' section to this "anatomy"
section.

Also, change the wording in the introductory paragraph to use
"contributions" instead of "patches", since this makes more sense when
talking about GitHub pull requests.

Signed-off-by: Philippe Blain <[e-mail]>
---
 Documentation/MyFirstContribution.txt | 54 +++++++++++++++++++++++++--
 1 file changed, 51 insertions(+), 3 deletions(-)

Patch

diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index 63a2ef54493..22848f84bec 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -710,13 +710,61 @@  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/[e-mail]/
+: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]:
+
+----
[phone]:40 [PATCH 0/3] libify reflog John Cai via GitGitGadget
[phone]:40 ` [PATCH 1/3] reflog: libify delete reflog function and helpers John Cai via GitGitGadget
[phone]:10   ` Ævar Arnfjörð Bjarmason [this message]
[phone]:39     ` Taylor Blau
[phone]:48       ` Ævar Arnfjörð Bjarmason
[phone]:35   ` Taylor Blau
[phone]:43     ` John Cai
[phone]:50       ` Taylor Blau
[phone]:50         ` John Cai
[phone]:00   ` // other replies ellided
[phone]:40 ` [PATCH 2/3] reflog: call reflog_delete from reflog.c John Cai via GitGitGadget
[phone]:15   ` Ævar Arnfjörð Bjarmason
[phone]:26     ` Junio C Hamano
[phone]:40 ` [PATCH 3/3] stash: call reflog_delete from reflog.c John Cai via GitGitGadget
[phone]:20   ` Ævar Arnfjörð Bjarmason
[phone]:21     ` Taylor Blau
[phone]:36     ` John Cai
[phone]:51       ` Ævar Arnfjörð Bjarmason
[phone]:29 ` [PATCH 0/3] libify reflog Ævar Arnfjörð Bjarmason
[phone]:30 ` [PATCH v2 0/3] libify reflog John Cai via GitGitGadget
[phone]:30   ` [PATCH v2 1/3] stash: add test to ensure reflog --rewrite --updatref behavior John Cai via GitGitGadget
[phone]:54     ` Ævar Arnfjörð Bjarmason
[phone]: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. and sent with a new cover letter, itself a reply to the cover
+  letter of the previous iteration (more on that below).
+
+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