[v2,2/5] MyFirstContribution: add standalone section on cover letter

Commit Message

Philippe Blain May 11, 2022, 1:47 a.m. UTC

From: Philippe Blain <[e-mail]>

An explanation of the purpose of the cover letter is included in the
"Sending Patches with git send-email" / "Preparing Email" section but is
missing from the "Sending Patches via GitGitGadget" section.

Add a standalone section "The cover letter" under the "Getting Started:
Anatomy of a Patch Series" header to explain what the cover letter is
used for and to draft the cover letter of the 'psuh' topic used in the
tutorial.

For now we mostly copy content from the "Sending Patches with git
send-email" section but do not adjust that section, nor the GGG section,
to reference the new section. This is done in following commits.

Also, adjust the "Preparing Email" Asciidoc anchor to avoid conflicts.

Signed-off-by: Philippe Blain <[e-mail]>
---
 Documentation/MyFirstContribution.txt | 39 ++++++++++++++++++++++++++-
 1 file changed, 38 insertions(+), 1 deletion(-)

Comments

Junio C Hamano May 11, 2022, 10:01 a.m. UTC | #1

"Philippe Blain via GitGitGadget" <[e-mail]> writes:

> +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 be in your commit messages, not in your cover letter.

I agree with only a half of the last sentence.

Things that are useful for "git log" readers should be in the commit
message (but that goes without saying---by definition "git log"
readers are reading commit messages).  If that material helps to
understand the overall topic structure by the reviewers, it is not
wrong to have that _also_ in your cover letter.  IOW, I sense that
"not in your cover letter" is a bit too strong.

Other than that, I found that 1/5 and 2/5 are very nicely written.

Thanks.

Philippe Blain May 11, 2022, 9:49 p.m. UTC | #2

Hi Junio,

Le 2022-05-11 à 06:01, Junio C Hamano a écrit :
> "Philippe Blain via GitGitGadget" <[e-mail]> writes:
> 
>> +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 be in your commit messages, not in your cover letter.
> 
> I agree with only a half of the last sentence.
> 
> Things that are useful for "git log" readers should be in the commit
> message (but that goes without saying---by definition "git log"
> readers are reading commit messages).  If that material helps to
> understand the overall topic structure by the reviewers, it is not
> wrong to have that _also_ in your cover letter.  IOW, I sense that
> "not in your cover letter" is a bit too strong.

OK, I'll tweak that in a v3.

> 
> Other than that, I found that 1/5 and 2/5 are very nicely written.

Thanks !:)

Patch

diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index 22848f84bec..de62a61771c 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -764,6 +764,43 @@  We can note a few things:
   v3]", etc. and sent with a new cover letter, itself a reply to the cover
   letter of the previous iteration (more on that below).
 
+[[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 be in your commit messages, not in your cover letter.
+
+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.
 
@@ -1000,7 +1037,7 @@  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