Changes since v2:
* tweaked 2/5 following Junio's comments (added more details, tweaked the
wording and added a note about single patch series).
v2: Thanks a lot for the reviews! Here is an updated version.
Changes since v1:
* Based on v1 feedback, instead of reusing the 'git send-email' content
verbatim in the GGG section, added a new section and reference it in both
'git send-email' and GGG sections. (patches 1/5-4/5)
* In patch 5/5 (patch 3/3 in v1), tweak wording and add a reference to the
"Bonus Chapter: One-Patch Changes" section.
v1: Two small improvements to the MyFirstContribution tutorial:
* Describe the purpose of the cover letter in that section also, and give
an example just as in the 'git send-email' section
* Instruct contributors to drop the GitHub-generated PR description for
single patch contributions.
Philippe Blain (5):
MyFirstContribution: add "Anatomy of a Patch Series" section
MyFirstContribution: add standalone section on cover letter
MyFirstContribution: reference "The cover letter" in "Preparing Email"
MyFirstContribution: reference "The cover letter" in GitGitGadget
section
MyFirstContribution: drop PR description for GGG single-patch
contributions
Documentation/MyFirstContribution.txt | 155 ++++++++++++++++++++------
1 file changed, 120 insertions(+), 35 deletions(-)
base-commit: 6cd33dceed60949e2dbc32e3f0f5e67c4c882e1e
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1226%2Fphil-blain%2Fmyfirst-contrib-single-patch-ggg-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1226/phil-blain/myfirst-contrib-single-patch-ggg-v3
Pull-Request: https://github.com/gitgitgadget/git/pull/1226
Range-diff vs v2:
1: 59af7e5e5ad = 1: 59af7e5e5ad MyFirstContribution: add "Anatomy of a Patch Series" section
2: 9552d80a80d ! 2: ee3238f5a91 MyFirstContribution: add standalone section on cover letter
@@ Commit message
## Documentation/MyFirstContribution.txt ##
@@ Documentation/MyFirstContribution.txt: 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).
-
+ _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).
++- 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
+
@@ Documentation/MyFirstContribution.txt: We can note a few things:
+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.
++should also be in your commit messages.
+
+Here's an example body for `psuh`:
+
@@ Documentation/MyFirstContribution.txt: We can note a few things:
+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.
-
@@ Documentation/MyFirstContribution.txt: 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!
3: d7699289ea6 = 3: 2caec6e619a MyFirstContribution: reference "The cover letter" in "Preparing Email"
4: f6034b0964b = 4: 02598d431e0 MyFirstContribution: reference "The cover letter" in GitGitGadget section
5: 33256c6b4ba = 5: 76bcb6612e4 MyFirstContribution: drop PR description for GGG single-patch contributions
--
gitgitgadget
