MyFirstContribution: reference "The cover letter" in "Preparing Email"
The previous commit added a standalone section on the purpose of the cover letter, drawing inspiration from the existing content of the "Preparing Email" section. Adjust "Preparing Email" to reference "The cover letter", to avoid content duplication. Also, use the imperative mode for the cover letter subject, as is done in "The cover letter". Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Philippe Blain committed
May 12, 2022 at 23:43 UTC
e97d474c7a7ba5c5ed0cfa56e100a9b22feb69ff
1 file changed
+9
-29
Documentation/MyFirstContribution.txt
+9
-29
@@ -1046,46 +1046,26 @@ directory you specified - you're nearly ready to send out your review!
1046
[[preparing-cover-letter]]
1047
=== Preparing Email
1048
1049
-In addition to an email per patch, the Git community also expects your patches
1050
-to come with a cover letter, typically with a subject line [PATCH 0/x] (where
1051
-x is the number of patches you're sending). Since you invoked `format-patch`
1052
-with `--cover-letter`, you've already got a template ready. Open it up in your
1053
-favorite editor.
1049
+Since you invoked `format-patch` with `--cover-letter`, you've already got a
1050
+cover letter template ready. Open it up in your favorite editor.
1051
1052
You should see a number of headers present already. Check that your `From:`
1056
-header is correct. Then modify your `Subject:` to something which succinctly
1057
-covers the purpose of your entire topic branch, for example:
1053
+header is correct. Then modify your `Subject:` (see <<cover-letter,above>> for
1054
+how to choose good title for your patch series):
1055
1056
----
1060
-Subject: [PATCH 0/7] adding the 'psuh' command
1057
+Subject: [PATCH 0/7] Add the 'psuh' command
1058
----
1059
1060
Make sure you retain the ``[PATCH 0/X]'' part; that's what indicates to the Git
1064
-community that this email is the beginning of a review, and many reviewers
1065
-filter their email for this type of flag.
1061
+community that this email is the beginning of a patch series, and many
1062
+reviewers filter their email for this type of flag.
1063
1064
You'll need to add some extra parameters when you invoke `git send-email` to add
1065
the cover letter.
1066
1070
-Next you'll have to fill out the body of your cover letter. This is an important
1071
-component of change submission as it explains to the community from a high level
1072
-what you're trying to do, and why, in a way that's more apparent than just
1073
-looking at your diff. Be sure to explain anything your diff doesn't make clear
1074
-on its own.
1075
-
1076
-Here's an example body for `psuh`:
1077
-
1078
-----
1079
-Our internal metrics indicate widespread interest in the command
1080
-git-psuh - that is, many users are trying to use it, but finding it is
1081
-unavailable, using some unknown workaround instead.
1082
-
1083
-The following handful of patches add the psuh command and implement some
1084
-handy features on top of it.
1085
-
1086
-This patchset is part of the MyFirstContribution tutorial and should not
1087
-be merged.
1088
-----
1067
+Next you'll have to fill out the body of your cover letter. Again, see
1068
+<<cover-letter,above>> for what content to include.
1069
1070
The template created by `git format-patch --cover-letter` includes a diffstat.
1071
This gives reviewers a summary of what they're in for when reviewing your topic.