MyFirstContribution: add standalone section on cover letter
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 <levraiphilippeblain@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Philippe Blain committed
May 12, 2022 at 23:43 UTC
afc8c92535749136e015ed8474b0db5613ad177d
1 file changed
+47
-4
Documentation/MyFirstContribution.txt
+47
-4
@@ -760,9 +760,52 @@ We can note a few things:
760
_n_-commit series.
761
- Each patch is sent as a reply to an introductory email called the _cover
762
letter_ of the series, prefixed "[PATCH 0/_n_]".
763
-- Subsequent iterations of the patch series are labelled "[PATCH v2]", "[PATCH
764
- v3]", etc. and sent with a new cover letter, itself a reply to the cover
765
- letter of the previous iteration (more on that below).
763
+- Subsequent iterations of the patch series are labelled "PATCH v2", "PATCH
764
+ v3", etc. in place of "PATCH". For example, "[PATCH v2 1/3]" would be the first of
765
+ three patches in the second iteration. Each iteration is sent with a new cover
766
+ letter (like "[PATCH v2 0/3]" above), itself a reply to the cover letter of the
767
+ previous iteration (more on that below).
768
+
769
+NOTE: A single-patch topic is sent with "[PATCH]", "[PATCH v2]", etc. without
770
+_i_/_n_ numbering (in the above thread overview, no single-patch topic appears,
771
+though).
772
+
773
+[[cover-letter]]
774
+=== The cover letter
775
+
776
+In addition to an email per patch, the Git community also expects your patches
777
+to come with a cover letter. This is an important component of change
778
+submission as it explains to the community from a high level what you're trying
779
+to do, and why, in a way that's more apparent than just looking at your
780
+patches.
781
+
782
+The title of your cover letter should be something which succinctly covers the
783
+purpose of your entire topic branch. It's often in the imperative mood, just
784
+like our commit message titles. Here is how we'll title our series:
785
+
786
+---
787
+Add the 'psuh' command
788
+---
789
+
790
+The body of the cover letter is used to give additional context to reviewers.
791
+Be sure to explain anything your patches don't make clear on their own, but
792
+remember that since the cover letter is not recorded in the commit history,
793
+anything that might be useful to future readers of the repository's history
794
+should also be in your commit messages.
795
+
796
+Here's an example body for `psuh`:
797
+
798
+----
799
+Our internal metrics indicate widespread interest in the command
800
+git-psuh - that is, many users are trying to use it, but finding it is
801
+unavailable, using some unknown workaround instead.
802
+
803
+The following handful of patches add the psuh command and implement some
804
+handy features on top of it.
805
+
806
+This patchset is part of the MyFirstContribution tutorial and should not
807
+be merged.
808
+----
809
810
At this point the tutorial diverges, in order to demonstrate two
811
different methods of formatting your patchset and getting it reviewed.
@@ -1000,7 +1043,7 @@ but want reviewers to look at what they have so far. You can add this flag with
1043
Check and make sure that your patches and cover letter template exist in the
1044
directory you specified - you're nearly ready to send out your review!
1045
1003
-[[cover-letter]]
1046
+[[preparing-cover-letter]]
1047
=== Preparing Email
1048
1049
In addition to an email per patch, the Git community also expects your patches