{"thread":{"id":"57807","subject":"[PATCH 3/3] MyFirstContribution: drop PR description for GGG single-patch contributions","startedAt":"2022-04-27T19:12:45Z","lastAt":"2022-05-24T19:06:45Z","messageCount":43,"participants":["Philippe Blain via GitGitGadget","Victoria Dye","Eric Sunshine","Junio C Hamano","Philippe Blain","Bagas Sanjaya","Philip Oakley"],"isPatch":true,"patchVersion":1,"patchTotal":3},"messages":[{"id":"454535","messageId":"2f6ecbf260135efc2a7ad09564cf6c64ed6d6f0d.1651086288.git.gitgitgadget@gmail.com","threadId":"57807","inReplyTo":"pull.1226.git.1651086288.gitgitgadget@gmail.com","subject":"[PATCH 3/3] MyFirstContribution: drop PR description for GGG single-patch contributions","fromName":"Philippe Blain via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-04-27T19:04:48Z","receivedAt":"2022-04-27T19:12:45Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"From: Philippe Blain \n\nBy default, GitHub prefills the PR description using the commit message\nfor single-commit PRs. This results in a duplicate commit message below\nthe three-dash line if the contributor does not empty out the PR\ndescription before submitting, which adds noise for reviewers.\n\nAdd a note to that effect in MyFirstContribution.txt.\n\nThis partly addresses:\nhttps://github.com/gitgitgadget/gitgitgadget/issues/340\n\nSigned-off-by: Philippe Blain \n---\n Documentation/MyFirstContribution.txt | 8 ++++++++\n 1 file changed, 8 insertions(+)\n\ndiff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt\nindex 96da32f7cef..2ce51d8c82e 100644\n--- a/Documentation/MyFirstContribution.txt\n+++ b/Documentation/MyFirstContribution.txt\n@@ -821,6 +821,14 @@ Adding the 'psuh' command\n Your PR's description will used as the body of the cover letter.\n include::MyFirstContribution-coverletter.txt[]\n \n+NOTE: For single-patch contributions, your commit message should already be\n+meaningful and explain at a high level the purpose (what is happening and why)\n+of your patch, so you usually do not need any additional context. In that case,\n+remove the PR description that GitHub automatically generates from your commit\n+message (your PR description should be empty). If you do need to supply even\n+more context, you can do so in that space and it will be appended to the email\n+that GitGitGadget will send, separately from your commit message.\n+\n When you're happy, submit your pull request.\n \n [[run-ci-ggg]]\n-- \ngitgitgadget\n"},{"id":"454536","messageId":"afb80b8e9ee022cba9373f2191ee1619e5897b09.1651086288.git.gitgitgadget@gmail.com","threadId":"57807","inReplyTo":"pull.1226.git.1651086288.gitgitgadget@gmail.com","subject":"[PATCH 2/3] MyFirstContribution: also explain cover letter in GitGitGadget section","fromName":"Philippe Blain via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-04-27T19:04:47Z","receivedAt":"2022-04-27T19:12:58Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"From: Philippe Blain \n\nThe \"Sending Patches via GitGitGadget\" section mentions that the PR\ntitle and description will be used as the cover letter, but does not\nexplain what is a cover letter or what should be included in it.\n\nMention the purpose of the cover letter in that section, and give\nexamples for the title and description, leveraging the excerpt extracted\nfrom the \"Sending Patches with git send-email\" section in the previous\ncommit.\n\nSigned-off-by: Philippe Blain \n---\n Documentation/MyFirstContribution.txt | 16 ++++++++++++++--\n 1 file changed, 14 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt\nindex 681bbefe9cd..96da32f7cef 100644\n--- a/Documentation/MyFirstContribution.txt\n+++ b/Documentation/MyFirstContribution.txt\n@@ -808,8 +808,20 @@ https://github.com/gitgitgadget/git and open a PR either with the \"New pull\n request\" button or the convenient \"Compare & pull request\" button that may\n appear with the name of your newly pushed branch.\n \n-Review the PR's title and description, as it's used by GitGitGadget as the cover\n-letter for your change. When you're happy, submit your pull request.\n+Review the PR's title and description, as they're used by GitGitGadget as the\n+cover letter for your change. The cover letter describes your proposed\n+contribution as a whole and is ideal to mention any context that might be\n+useful for reviewers. The title of your PR should be something which\n+succinctly covers the purpose of your entire topic branch, for example:\n+\n+----\n+Adding the 'psuh' command\n+----\n+\n+Your PR's description will used as the body of the cover letter.\n+include::MyFirstContribution-coverletter.txt[]\n+\n+When you're happy, submit your pull request.\n \n [[run-ci-ggg]]\n === Running CI and Getting Ready to Send\n-- \ngitgitgadget\n\n"},{"id":"454537","messageId":"7e84d5b286de9dddf28ef1c8f38c7d7c28e266f0.1651086288.git.gitgitgadget@gmail.com","threadId":"57807","inReplyTo":"pull.1226.git.1651086288.gitgitgadget@gmail.com","subject":"[PATCH 1/3] MyFirstContribution: move cover letter description to a separate file","fromName":"Philippe Blain via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-04-27T19:04:46Z","receivedAt":"2022-04-27T19:13:00Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"From: Philippe Blain \n\nIn a subsequent commit we want to reuse the explanation of the purpose of\nThe cover letter form the \"Sending Patches with git send-email\" section\nin the \"Sending Patches via GitGitGadget\" section.\n\nTo avoid text duplication, move this explanation to a separate file and\ninclude it in MyFirstContribution.txt.\n\nSigned-off-by: Philippe Blain \n---\n .../MyFirstContribution-coverletter.txt | 18 ++++++++++++++++\n Documentation/MyFirstContribution.txt | 21 ++-----------------\n 2 files changed, 20 insertions(+), 19 deletions(-)\n create mode 100644 Documentation/MyFirstContribution-coverletter.txt\n\ndiff --git a/Documentation/MyFirstContribution-coverletter.txt b/Documentation/MyFirstContribution-coverletter.txt\nnew file mode 100644\nindex 00000000000..b9e1e10427a\n--- /dev/null\n+++ b/Documentation/MyFirstContribution-coverletter.txt\n@@ -0,0 +1,18 @@\n+This is an important component of change submission as it explains to the\n+community from a high level what you're trying to do, and why, in a way that's\n+more apparent than just looking at your diff. Be sure to explain anything your\n+diff doesn't make clear on its own.\n+\n+Here's an example body for `psuh`:\n+\n+----\n+Our internal metrics indicate widespread interest in the command\n+git-psuh - that is, many users are trying to use it, but finding it is\n+unavailable, using some unknown workaround instead.\n+\n+The following handful of patches add the psuh command and implement some\n+handy features on top of it.\n+\n+This patchset is part of the MyFirstContribution tutorial and should not\n+be merged.\n+----\ndiff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt\nindex 63a2ef54493..681bbefe9cd 100644\n--- a/Documentation/MyFirstContribution.txt\n+++ b/Documentation/MyFirstContribution.txt\n@@ -976,25 +976,8 @@ filter their email for this type of flag.\n You'll need to add some extra parameters when you invoke `git send-email` to add\n the cover letter.\n \n-Next you'll have to fill out the body of your cover letter. This is an important\n-component of change submission as it explains to the community from a high level\n-what you're trying to do, and why, in a way that's more apparent than just\n-looking at your diff. Be sure to explain anything your diff doesn't make clear\n-on its own.\n-\n-Here's an example body for `psuh`:\n-\n-----\n-Our internal metrics indicate widespread interest in the command\n-git-psuh - that is, many users are trying to use it, but finding it is\n-unavailable, using some unknown workaround instead.\n-\n-The following handful of patches add the psuh command and implement some\n-handy features on top of it.\n-\n-This patchset is part of the MyFirstContribution tutorial and should not\n-be merged.\n-----\n+Next you'll have to fill out the body of your cover letter.\n+include::MyFirstContribution-coverletter.txt[]\n \n The template created by `git format-patch --cover-letter` includes a diffstat.\n This gives reviewers a summary of what they're in for when reviewing your topic.\n-- \ngitgitgadget\n\n"},{"id":"454538","messageId":"pull.1226.git.1651086288.gitgitgadget@gmail.com","threadId":"57807","inReplyTo":null,"subject":"[PATCH 0/3] Improve MyFirstContribution's GitGitGadget section","fromName":"Philippe Blain via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-04-27T19:04:45Z","receivedAt":"2022-04-27T19:13:02Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"Two small improvements to the MyFirstContribution tutorial:\n\n * Describe the purpose of the cover letter in that section also, and give\n an example just as in the 'git send-email' section\n * Instruct contributors to drop the GitHub-generated PR description for\n single patch contributions.\n\nPhilippe Blain (3):\n MyFirstContribution: move cover letter description to a separate file\n MyFirstContribution: also explain cover letter in GitGitGadget section\n MyFirstContribution: drop PR description for GGG single-patch\n contributions\n\n .../MyFirstContribution-coverletter.txt | 18 ++++++++\n Documentation/MyFirstContribution.txt | 45 ++++++++++---------\n 2 files changed, 42 insertions(+), 21 deletions(-)\n create mode 100644 Documentation/MyFirstContribution-coverletter.txt\n\n\nbase-commit: 6cd33dceed60949e2dbc32e3f0f5e67c4c882e1e\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1226%2Fphil-blain%2Fmyfirst-contrib-single-patch-ggg-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1226/phil-blain/myfirst-contrib-single-patch-ggg-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/1226\n-- \ngitgitgadget\n"},{"id":"454545","messageId":"ed4a0e46-a45c-0b05-fc35-f82e377ea231@github.com","threadId":"57807","inReplyTo":"afb80b8e9ee022cba9373f2191ee1619e5897b09.1651086288.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 2/3] MyFirstContribution: also explain cover letter in GitGitGadget section","fromName":"Victoria Dye","fromEmail":"vdye@github.com","sentAt":"2022-04-27T20:43:28Z","receivedAt":"2022-04-27T20:43:37Z","isPatch":true,"sender":{"key":"vdye@github.com","avatar":"https://avatars.githubusercontent.com/u/3619353?v=4"},"body":"Philippe Blain via GitGitGadget wrote:\n> From: Philippe Blain \n> \n> The \"Sending Patches via GitGitGadget\" section mentions that the PR\n> title and description will be used as the cover letter, but does not\n> explain what is a cover letter or what should be included in it.\n> \n> Mention the purpose of the cover letter in that section, and give\n> examples for the title and description, leveraging the excerpt extracted\n> from the \"Sending Patches with git send-email\" section in the previous\n> commit.\n> \n> Signed-off-by: Philippe Blain \n> ---\n> Documentation/MyFirstContribution.txt | 16 ++++++++++++++--\n> 1 file changed, 14 insertions(+), 2 deletions(-)\n> \n> diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt\n> index 681bbefe9cd..96da32f7cef 100644\n> --- a/Documentation/MyFirstContribution.txt\n> +++ b/Documentation/MyFirstContribution.txt\n> @@ -808,8 +808,20 @@ https://github.com/gitgitgadget/git and open a PR either with the \"New pull\n> request\" button or the convenient \"Compare & pull request\" button that may\n> appear with the name of your newly pushed branch.\n> \n> -Review the PR's title and description, as it's used by GitGitGadget as the cover\n> -letter for your change. When you're happy, submit your pull request.\n> +Review the PR's title and description, as they're used by GitGitGadget as the\n> +cover letter for your change. The cover letter describes your proposed\n> +contribution as a whole and is ideal to mention any context that might be\n> +useful for reviewers. The title of your PR should be something which\n> +succinctly covers the purpose of your entire topic branch, for example:\n> +\n> +----\n> +Adding the 'psuh' command\n\nTypically I see patch series titles follow the same \"imperative mood\" as\ncommit titles/messages (see 'Documentation/SubmittingPatches.txt'). I'm not\nsure whether that's a rule written down somewhere or just convention, but\nfor the sake of consistency you might want to do something like:\n\n\t\"Add the 'psuh' command\"\n\n> +----\n> +\n> +Your PR's description will used as the body of the cover letter.\n\nIncluding the line \"Your PR's description...\" is somewhat confusing to me as\na first-time reader, since I was interpreting this section to be the\n*verbatim* text of the pull request title & description. If this *is* meant\nto be that description, then the note about the PR description can be\nremoved. That point is also mentioned above, so it's probably not needed\nhere anyway.\n\n> +include::MyFirstContribution-coverletter.txt[]\n> +\n> +When you're happy, submit your pull request.\n> \n> [[run-ci-ggg]]\n> === Running CI and Getting Ready to Send\n\n"},{"id":"454550","messageId":"CAPig+cRgD8LjQxnoJQre+sb2NcO2yHz19fPfAQsdYdSYUgyjLA@mail.gmail.com","threadId":"57807","inReplyTo":"7e84d5b286de9dddf28ef1c8f38c7d7c28e266f0.1651086288.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 1/3] MyFirstContribution: move cover letter description to a separate file","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2022-04-27T21:15:26Z","receivedAt":"2022-04-27T21:16:36Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Wed, Apr 27, 2022 at 3:18 PM Philippe Blain via GitGitGadget\n wrote:\n> In a subsequent commit we want to reuse the explanation of the purpose of\n> The cover letter form the \"Sending Patches with git send-email\" section\n\ns/The/the\ns/form/from/\n\n> in the \"Sending Patches via GitGitGadget\" section.\n>\n> To avoid text duplication, move this explanation to a separate file and\n> include it in MyFirstContribution.txt.\n>\n> Signed-off-by: Philippe Blain \n"},{"id":"454552","messageId":"xmqqr15ijiyt.fsf@gitster.g","threadId":"57807","inReplyTo":"7e84d5b286de9dddf28ef1c8f38c7d7c28e266f0.1651086288.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 1/3] MyFirstContribution: move cover letter description to a separate file","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-04-27T21:48:42Z","receivedAt":"2022-04-27T21:48:48Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philippe Blain via GitGitGadget\" writes:\n\n> From: Philippe Blain \n>\n> In a subsequent commit we want to reuse the explanation of the purpose of\n> The cover letter form the \"Sending Patches with git send-email\" section\n> in the \"Sending Patches via GitGitGadget\" section.\n>\n> To avoid text duplication, move this explanation to a separate file and\n> include it in MyFirstContribution.txt.\n>\n> Signed-off-by: Philippe Blain \n> ---\n> .../MyFirstContribution-coverletter.txt | 18 ++++++++++++++++\n> Documentation/MyFirstContribution.txt | 21 ++-----------------\n> 2 files changed, 20 insertions(+), 19 deletions(-)\n> create mode 100644 Documentation/MyFirstContribution-coverletter.txt\n\nIf the end-product is a single document, \"MyFirstContribution\", I am\nskeptical if it is a good change to duplicate the same text in two\nsections.\n\nShould we instead reorganize the document so these concepts like\ncover letters, log message for each commit, etc., which are\napplicable regardless of how you send them out, are explained,\nbefore we start talking about \"now, we understand the components out\nof which a patch series is made of, here is how you give it a final\npolish and send it out, with send-email and/or with GGG\"?\n\nShort of that, perhaps whichever appears later in the document that\nuses \"cover letter\" can just say \"see above\"?\n\n"},{"id":"454554","messageId":"xmqqmtg6jim2.fsf@gitster.g","threadId":"57807","inReplyTo":"2f6ecbf260135efc2a7ad09564cf6c64ed6d6f0d.1651086288.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 3/3] MyFirstContribution: drop PR description for GGG single-patch contributions","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-04-27T21:56:21Z","receivedAt":"2022-04-27T21:56:36Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philippe Blain via GitGitGadget\" writes:\n\n> +NOTE: For single-patch contributions, your commit message should already be\n> +meaningful and explain at a high level the purpose (what is happening and why)\n> +of your patch, so you usually do not need any additional context. In that case,\n> +remove the PR description that GitHub automatically generates from your commit\n> +message (your PR description should be empty). If you do need to supply even\n> +more context, you can do so in that space and it will be appended to the email\n> +that GitGitGadget will send, separately from your commit message.\n\n\"separately from your commit message\" wants to be clarified. It\nsounds as if GGG will send a separate message.\n\nI am _guessing_ that you meant something like \"the body of your\nproposed log message ends with your sign-off and followed by a line\nwith three-dashes on it. After that three-dash line, and before the\ndiffstat and the patch, is an appropriate place to write additional\ninformation that are meant to help reviewers during review but will\nbecome irrelevant after the review is done. Your PR description\nwill appear there for a single patch contribution\".\n\nIf we do not explain the space after the three-dash line elsewhere,\nperhaps we should do so separately, like we talk about cover\nletters.\n\nThanks.\n"},{"id":"454555","messageId":"8c22e4bd-e176-4ff9-a286-05d6ba17a1b1@gmail.com","threadId":"57807","inReplyTo":"CAPig+cRgD8LjQxnoJQre+sb2NcO2yHz19fPfAQsdYdSYUgyjLA@mail.gmail.com","subject":"Re: [PATCH 1/3] MyFirstContribution: move cover letter description to a separate file","fromName":"Philippe Blain","fromEmail":"levraiphilippeblain@gmail.com","sentAt":"2022-04-27T22:02:42Z","receivedAt":"2022-04-27T22:02:42Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"Hi Eric,\n\nLe 2022-04-27 à 17:15, Eric Sunshine a écrit :\n> On Wed, Apr 27, 2022 at 3:18 PM Philippe Blain via GitGitGadget\n> wrote:\n>> In a subsequent commit we want to reuse the explanation of the purpose of\n>> The cover letter form the \"Sending Patches with git send-email\" section\n> \n> s/The/the\n> s/form/from/\n> \n\nIndeed, will fix. Thanks,\nPhilippe.\n"},{"id":"454583","messageId":"706e34fb-fb0c-e86d-5d0f-0bd052566b3a@gmail.com","threadId":"57807","inReplyTo":"xmqqr15ijiyt.fsf@gitster.g","subject":"Re: [PATCH 1/3] MyFirstContribution: move cover letter description to a separate file","fromName":"Philippe Blain","fromEmail":"levraiphilippeblain@gmail.com","sentAt":"2022-04-28T18:16:56Z","receivedAt":"2022-04-28T18:17:13Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"Hi Junio,\n\nLe 2022-04-27 à 17:48, Junio C Hamano a écrit :\n> \"Philippe Blain via GitGitGadget\" writes:\n> \n>> From: Philippe Blain \n>>\n>> In a subsequent commit we want to reuse the explanation of the purpose of\n>> The cover letter form the \"Sending Patches with git send-email\" section\n>> in the \"Sending Patches via GitGitGadget\" section.\n>>\n>> To avoid text duplication, move this explanation to a separate file and\n>> include it in MyFirstContribution.txt.\n>>\n>> Signed-off-by: Philippe Blain \n>> ---\n>> .../MyFirstContribution-coverletter.txt | 18 ++++++++++++++++\n>> Documentation/MyFirstContribution.txt | 21 ++-----------------\n>> 2 files changed, 20 insertions(+), 19 deletions(-)\n>> create mode 100644 Documentation/MyFirstContribution-coverletter.txt\n> \n> If the end-product is a single document, \"MyFirstContribution\", I am\n> skeptical if it is a good change to duplicate the same text in two\n> sections.\n> \n> Should we instead reorganize the document so these concepts like\n> cover letters, log message for each commit, etc., which are\n> applicable regardless of how you send them out, are explained,\n> before we start talking about \"now, we understand the components out\n> of which a patch series is made of, here is how you give it a final\n> polish and send it out, with send-email and/or with GGG\"?\n> \n> Short of that, perhaps whichever appears later in the document that\n> uses \"cover letter\" can just say \"see above\"?\n> \n\nYeah, I guess you are right. I choosed to factor out the cover letter\npart like this mostly because it was a smaller change. I'll think of doing\nit like you suggest.\n\nThanks,\nPhilippe.\n"},{"id":"454584","messageId":"c7030c98-bd65-7d0e-89ac-ae291e22b10d@gmail.com","threadId":"57807","inReplyTo":"ed4a0e46-a45c-0b05-fc35-f82e377ea231@github.com","subject":"Re: [PATCH 2/3] MyFirstContribution: also explain cover letter in GitGitGadget section","fromName":"Philippe Blain","fromEmail":"levraiphilippeblain@gmail.com","sentAt":"2022-04-28T18:21:15Z","receivedAt":"2022-04-28T18:21:22Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"Hi Victoria,\n\nLe 2022-04-27 à 16:43, Victoria Dye a écrit :\n> Philippe Blain via GitGitGadget wrote:\n\n>> +----\n>> +Adding the 'psuh' command\n> \n> Typically I see patch series titles follow the same \"imperative mood\" as\n> commit titles/messages (see 'Documentation/SubmittingPatches.txt'). I'm not\n> sure whether that's a rule written down somewhere or just convention, but\n> for the sake of consistency you might want to do something like:\n> \n> \t\"Add the 'psuh' command\"\n> \n\nI fully agree. I just copied the existing patch series title from \nthe git-send-email section further down. I think it would make sense\nto change this to also using the imperative mood just like commit messages\nin a preparatory commit. I'll do that.\n\n>> +----\n>> +\n>> +Your PR's description will used as the body of the cover letter.\n> \n> Including the line \"Your PR's description...\" is somewhat confusing to me as\n> a first-time reader, since I was interpreting this section to be the\n> *verbatim* text of the pull request title & description. If this *is* meant\n> to be that description, then the note about the PR description can be\n> removed. That point is also mentioned above, so it's probably not needed\n> here anyway.\n\nI'm not exactly sure what you mean. I meant that the description of the PR\nwill be used as the body of the cover letter...\n\nThanks for having a look!\n\nPhilippe.\n"},{"id":"454585","messageId":"73b8834b-c2be-7e47-0f77-4853a5a051b7@gmail.com","threadId":"57807","inReplyTo":"xmqqmtg6jim2.fsf@gitster.g","subject":"Re: [PATCH 3/3] MyFirstContribution: drop PR description for GGG single-patch contributions","fromName":"Philippe Blain","fromEmail":"levraiphilippeblain@gmail.com","sentAt":"2022-04-28T18:25:59Z","receivedAt":"2022-04-28T18:26:07Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"\n\nLe 2022-04-27 à 17:56, Junio C Hamano a écrit :\n> \"Philippe Blain via GitGitGadget\" writes:\n> \n>> +NOTE: For single-patch contributions, your commit message should already be\n>> +meaningful and explain at a high level the purpose (what is happening and why)\n>> +of your patch, so you usually do not need any additional context. In that case,\n>> +remove the PR description that GitHub automatically generates from your commit\n>> +message (your PR description should be empty). If you do need to supply even\n>> +more context, you can do so in that space and it will be appended to the email\n>> +that GitGitGadget will send, separately from your commit message.\n> \n> \"separately from your commit message\" wants to be clarified. It\n> sounds as if GGG will send a separate message.\n> \n> I am _guessing_ that you meant something like \"the body of your\n> proposed log message ends with your sign-off and followed by a line\n> with three-dashes on it. After that three-dash line, and before the\n> diffstat and the patch, is an appropriate place to write additional\n> information that are meant to help reviewers during review but will\n> become irrelevant after the review is done. Your PR description\n> will appear there for a single patch contribution\".\n\nYes, this is what I meant. I'll try to phrase it differently.\n\n> \n> If we do not explain the space after the three-dash line elsewhere,\n> perhaps we should do so separately, like we talk about cover\n> letters.\n\nYeah, it is explained in the \"Bonus Chapter: One-Patch Changes\" subsection [1]\nat the end of the \"Sending Patches with git send-email\" section, so I guess\npeople only reading the GitGitGadget instructions will not read that far...\n\nConsidering your other comment, I think that a little section titled something like\n\"Anatomy of a patch series\" would make sense to introduce how then end product\nlooks like and then the sections on GGG or git-send-email can reference this earlier section.\n\nGood idea.\nThanks!\n\nPhilippe.\n\n\n[1] https://git-scm.com/docs/MyFirstContribution#single-patch\n"},{"id":"454587","messageId":"xmqqo80lf0yj.fsf@gitster.g","threadId":"57807","inReplyTo":"73b8834b-c2be-7e47-0f77-4853a5a051b7@gmail.com","subject":"Re: [PATCH 3/3] MyFirstContribution: drop PR description for GGG single-patch contributions","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-04-28T19:43:32Z","receivedAt":"2022-04-28T19:43:37Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philippe Blain writes:\n\n> Considering your other comment, I think that a little section\n> titled something like \"Anatomy of a patch series\" would make sense\n> to introduce how then end product looks like and then the sections\n> on GGG or git-send-email can reference this earlier section.\n\n\"Anatomy\" does sound like a good idea.\n\n"},{"id":"454623","messageId":"f7f64135-7d57-5926-501b-13e83411b4fd@github.com","threadId":"57807","inReplyTo":"c7030c98-bd65-7d0e-89ac-ae291e22b10d@gmail.com","subject":"Re: [PATCH 2/3] MyFirstContribution: also explain cover letter in GitGitGadget section","fromName":"Victoria Dye","fromEmail":"vdye@github.com","sentAt":"2022-04-29T16:27:22Z","receivedAt":"2022-04-29T16:27:32Z","isPatch":true,"sender":{"key":"vdye@github.com","avatar":"https://avatars.githubusercontent.com/u/3619353?v=4"},"body":"Philippe Blain wrote:\n> Hi Victoria,\n> \n> Le 2022-04-27 à 16:43, Victoria Dye a écrit :\n>> Philippe Blain via GitGitGadget wrote:\n> \n>>> +----\n>>> +Adding the 'psuh' command\n>>\n>> Typically I see patch series titles follow the same \"imperative mood\" as\n>> commit titles/messages (see 'Documentation/SubmittingPatches.txt'). I'm not\n>> sure whether that's a rule written down somewhere or just convention, but\n>> for the sake of consistency you might want to do something like:\n>>\n>> \t\"Add the 'psuh' command\"\n>>\n> \n> I fully agree. I just copied the existing patch series title from \n> the git-send-email section further down. I think it would make sense\n> to change this to also using the imperative mood just like commit messages\n> in a preparatory commit. I'll do that.\n> \n>>> +----\n>>> +\n>>> +Your PR's description will used as the body of the cover letter.\n>>\n>> Including the line \"Your PR's description...\" is somewhat confusing to me as\n>> a first-time reader, since I was interpreting this section to be the\n>> *verbatim* text of the pull request title & description. If this *is* meant\n>> to be that description, then the note about the PR description can be\n>> removed. That point is also mentioned above, so it's probably not needed\n>> here anyway.\n> \n> I'm not exactly sure what you mean. I meant that the description of the PR\n> will be used as the body of the cover letter...\n> \n\nSorry for being unclear. What I meant was that, the way this part of the\ndocument reads (to me) right now, it looks like the recommendation is to\ncreate a pull request with the title & description:\n\nTitle: \n\tAdding the 'psuh' command\nDescription:\n\tYour PR's description will [be] used as the body of the cover\n\tletter. \n\nThat is, the line \"Your PR description will...\" is the first line of the\ndescription (which I don't think was your intention).\n\nThat said, upon a more holistic re-read, I've found a few more things that\nare confusing/oddly phrased. I'll try re-reviewing (part of) the patch\nbelow, with (hopefully) more direct/concrete feedback this time:\n\n> -Review the PR's title and description, as it's used by GitGitGadget as the cover\n> -letter for your change. When you're happy, submit your pull request.\n> +Review the PR's title and description, as they're used by GitGitGadget as the\n> +cover letter for your change. The cover letter describes your proposed\n> +contribution as a whole and is ideal to mention any context that might be\n\ns/is ideal to/should(?)\n\n> +useful for reviewers. The title of your PR should be something which\n> +succinctly covers the purpose of your entire topic branch, for example:\n> +\n> +----\n> +Adding the 'psuh' command\n> +----\n\nOther than the \"Adding\" -> \"Add\" change, this is good - the example title\nwill be formatted as a monospaced block, clearly separating it from the\nadvice/context preceding it.\n\n> +\n> +Your PR's description will used as the body of the cover letter.\n> +include::MyFirstContribution-coverletter.txt[]\n> +\n\nConversely, this section has no visible separation between the context\n(\"Your PR's description...\") and the example\n(\"include::MyFirstContribution-coverletter.txt[]\"), hence my confusion\nearlier. \n\nTo parallel the title example, maybe you could use similar monospace\nformatting for the example? E.g.:\n\n+\n+Your PR's description will used as the body of the cover letter.\n+ \n+----\n+include::MyFirstContribution-coverletter.txt[]\n+----\n+\n\nOne thing I noticed on my re-read is that the context you provide for the\ntitle (\"The title of your PR should be something...\") isn't quite paralleled\nin the context for the description (\"Your PR's description...\"). The former\ntalks about *how* you should write your cover letter title, whereas the\nlatter simply states that the PR description will become the cover letter's\ncontent. For added context, then, you might want to describe how the cover\nletter content should be written, e.g.:\n\n+\n+Your PR's description will be used as the body of the cover letter and\n+should explain the purpose of the series, for example:\n+ \n+----\n+include::MyFirstContribution-coverletter.txt[]\n+----\n+\n\n(note the s/will used/will be used)\n\nApologies for all the picky grammar comments - this series includes a lot of\nreally helpful information for new contributors, and I really appreciate\nyour work here! Hopefully my feedback is a bit more clear this time (and is\nrelatively straightforward to implement).\n\nThanks!\n\n\n> Thanks for having a look!\n> \n> Philippe.\n\n"},{"id":"455140","messageId":"875578c1-c3a9-bccb-40a7-b390b6a123ef@gmail.com","threadId":"57807","inReplyTo":"f7f64135-7d57-5926-501b-13e83411b4fd@github.com","subject":"Re: [PATCH 2/3] MyFirstContribution: also explain cover letter in GitGitGadget section","fromName":"Philippe Blain","fromEmail":"levraiphilippeblain@gmail.com","sentAt":"2022-05-10T23:45:35Z","receivedAt":"2022-05-10T23:45:43Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"Hi Victoria,\n\nLe 2022-04-29 à 12:27, Victoria Dye a écrit :\n> Philippe Blain wrote:\n>> Hi Victoria,\n>>\n>> Le 2022-04-27 à 16:43, Victoria Dye a écrit :\n>>> Philippe Blain via GitGitGadget wrote:\n>>\n>>>> +----\n>>>> +Adding the 'psuh' command\n>>>\n>>> Typically I see patch series titles follow the same \"imperative mood\" as\n>>> commit titles/messages (see 'Documentation/SubmittingPatches.txt'). I'm not\n>>> sure whether that's a rule written down somewhere or just convention, but\n>>> for the sake of consistency you might want to do something like:\n>>>\n>>> \t\"Add the 'psuh' command\"\n>>>\n>>\n>> I fully agree. I just copied the existing patch series title from \n>> the git-send-email section further down. I think it would make sense\n>> to change this to also using the imperative mood just like commit messages\n>> in a preparatory commit. I'll do that.\n>>\n>>>> +----\n>>>> +\n>>>> +Your PR's description will used as the body of the cover letter.\n>>>\n>>> Including the line \"Your PR's description...\" is somewhat confusing to me as\n>>> a first-time reader, since I was interpreting this section to be the\n>>> *verbatim* text of the pull request title & description. If this *is* meant\n>>> to be that description, then the note about the PR description can be\n>>> removed. That point is also mentioned above, so it's probably not needed\n>>> here anyway.\n>>\n>> I'm not exactly sure what you mean. I meant that the description of the PR\n>> will be used as the body of the cover letter...\n>>\n> \n> Sorry for being unclear. What I meant was that, the way this part of the\n> document reads (to me) right now, it looks like the recommendation is to\n> create a pull request with the title & description:\n> \n> Title: \n> \tAdding the 'psuh' command\n> Description:\n> \tYour PR's description will [be] used as the body of the cover\n> \tletter. \n> \n> That is, the line \"Your PR description will...\" is the first line of the\n> description (which I don't think was your intention).\n> \n> That said, upon a more holistic re-read, I've found a few more things that\n> are confusing/oddly phrased. I'll try re-reviewing (part of) the patch\n> below, with (hopefully) more direct/concrete feedback this time:\n> \n>> -Review the PR's title and description, as it's used by GitGitGadget as the cover\n>> -letter for your change. When you're happy, submit your pull request.\n>> +Review the PR's title and description, as they're used by GitGitGadget as the\n>> +cover letter for your change. The cover letter describes your proposed\n>> +contribution as a whole and is ideal to mention any context that might be\n> \n> s/is ideal to/should(?)\n> \n>> +useful for reviewers. The title of your PR should be something which\n>> +succinctly covers the purpose of your entire topic branch, for example:\n>> +\n>> +----\n>> +Adding the 'psuh' command\n>> +----\n> \n> Other than the \"Adding\" -> \"Add\" change, this is good - the example title\n> will be formatted as a monospaced block, clearly separating it from the\n> advice/context preceding it.\n> \n>> +\n>> +Your PR's description will used as the body of the cover letter.\n>> +include::MyFirstContribution-coverletter.txt[]\n>> +\n> \n> Conversely, this section has no visible separation between the context\n> (\"Your PR's description...\") and the example\n> (\"include::MyFirstContribution-coverletter.txt[]\"), hence my confusion\n> earlier. \n> \n> To parallel the title example, maybe you could use similar monospace\n> formatting for the example? E.g.:\n> \n> +\n> +Your PR's description will used as the body of the cover letter.\n> + \n> +----\n> +include::MyFirstContribution-coverletter.txt[]\n> +----\n> +\n> \n> One thing I noticed on my re-read is that the context you provide for the\n> title (\"The title of your PR should be something...\") isn't quite paralleled\n> in the context for the description (\"Your PR's description...\"). The former\n> talks about *how* you should write your cover letter title, whereas the\n> latter simply states that the PR description will become the cover letter's\n> content. For added context, then, you might want to describe how the cover\n> letter content should be written, e.g.:\n> \n> +\n> +Your PR's description will be used as the body of the cover letter and\n> +should explain the purpose of the series, for example:\n> + \n> +----\n> +include::MyFirstContribution-coverletter.txt[]\n> +----\n> +\n> \n> (note the s/will used/will be used)\n> \n> Apologies for all the picky grammar comments - this series includes a lot of\n> really helpful information for new contributors, and I really appreciate\n> your work here! Hopefully my feedback is a bit more clear this time (and is\n> relatively straightforward to implement).\n\nThanks for your feedback. I'll send an updated and expanded version soon\nand I think I've adressed the different things you noted.\n\nCheers,\n\nPhilippe.\n\n"},{"id":"455144","messageId":"pull.1226.v2.git.1652233654.gitgitgadget@gmail.com","threadId":"57807","inReplyTo":"pull.1226.git.1651086288.gitgitgadget@gmail.com","subject":"[PATCH v2 0/5] Improve MyFirstContribution's GitGitGadget section","fromName":"Philippe Blain via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-05-11T01:47:29Z","receivedAt":"2022-05-11T01:47:45Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"Thanks a lot for the reviews! Here is an updated version.\n\nChanges since v1:\n\n * Based on v1 feedback, instead of reusing the 'git send-email' content\n verbatim in the GGG section, added a new section and reference it in both\n 'git send-email' and GGG sections. (patches 1/5-4/5)\n * In patch 5/5 (patch 3/3 in v1), tweak wording and add a reference to the\n \"Bonus Chapter: One-Patch Changes\" section.\n\nv1: Two small improvements to the MyFirstContribution tutorial:\n\n * Describe the purpose of the cover letter in that section also, and give\n an example just as in the 'git send-email' section\n * Instruct contributors to drop the GitHub-generated PR description for\n single patch contributions.\n\nPhilippe Blain (5):\n MyFirstContribution: add \"Anatomy of a Patch Series\" section\n MyFirstContribution: add standalone section on cover letter\n MyFirstContribution: reference \"The cover letter\" in \"Preparing Email\"\n MyFirstContribution: reference \"The cover letter\" in GitGitGadget\n section\n MyFirstContribution: drop PR description for GGG single-patch\n contributions\n\n Documentation/MyFirstContribution.txt | 149 ++++++++++++++++++++------\n 1 file changed, 114 insertions(+), 35 deletions(-)\n\n\nbase-commit: 6cd33dceed60949e2dbc32e3f0f5e67c4c882e1e\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1226%2Fphil-blain%2Fmyfirst-contrib-single-patch-ggg-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1226/phil-blain/myfirst-contrib-single-patch-ggg-v2\nPull-Request: https://github.com/gitgitgadget/git/pull/1226\n\nRange-diff vs v1:\n\n -: ----------- > 1: 59af7e5e5ad MyFirstContribution: add \"Anatomy of a Patch Series\" section\n -: ----------- > 2: 9552d80a80d MyFirstContribution: add standalone section on cover letter\n 1: 7e84d5b286d ! 3: d7699289ea6 MyFirstContribution: move cover letter description to a separate file\n @@ Metadata\n Author: Philippe Blain \n \n ## Commit message ##\n - MyFirstContribution: move cover letter description to a separate file\n + MyFirstContribution: reference \"The cover letter\" in \"Preparing Email\"\n \n - In a subsequent commit we want to reuse the explanation of the purpose of\n - The cover letter form the \"Sending Patches with git send-email\" section\n - in the \"Sending Patches via GitGitGadget\" section.\n + The previous commit added a standalone section on the purpose of the\n + cover letter, drawing inspiration from the existing content of the\n + \"Preparing Email\" section.\n \n - To avoid text duplication, move this explanation to a separate file and\n - include it in MyFirstContribution.txt.\n + Adjust \"Preparing Email\" to reference \"The cover letter\", to avoid\n + content duplication.\n \n - Signed-off-by: Philippe Blain \n + Also, use the imperative mode for the cover letter subject, as is done\n + in \"The cover letter\".\n \n - ## Documentation/MyFirstContribution-coverletter.txt (new) ##\n -@@\n -+This is an important component of change submission as it explains to the\n -+community from a high level what you're trying to do, and why, in a way that's\n -+more apparent than just looking at your diff. Be sure to explain anything your\n -+diff doesn't make clear on its own.\n -+\n -+Here's an example body for `psuh`:\n -+\n -+----\n -+Our internal metrics indicate widespread interest in the command\n -+git-psuh - that is, many users are trying to use it, but finding it is\n -+unavailable, using some unknown workaround instead.\n -+\n -+The following handful of patches add the psuh command and implement some\n -+handy features on top of it.\n -+\n -+This patchset is part of the MyFirstContribution tutorial and should not\n -+be merged.\n -+----\n + Signed-off-by: Philippe Blain \n \n ## Documentation/MyFirstContribution.txt ##\n -@@ Documentation/MyFirstContribution.txt: filter their email for this type of flag.\n +@@ Documentation/MyFirstContribution.txt: directory you specified - you're nearly ready to send out your review!\n + [[preparing-cover-letter]]\n + === Preparing Email\n + \n +-In addition to an email per patch, the Git community also expects your patches\n +-to come with a cover letter, typically with a subject line [PATCH 0/x] (where\n +-x is the number of patches you're sending). Since you invoked `format-patch`\n +-with `--cover-letter`, you've already got a template ready. Open it up in your\n +-favorite editor.\n ++Since you invoked `format-patch` with `--cover-letter`, you've already got a\n ++cover letter template ready. Open it up in your favorite editor.\n + \n + You should see a number of headers present already. Check that your `From:`\n +-header is correct. Then modify your `Subject:` to something which succinctly\n +-covers the purpose of your entire topic branch, for example:\n ++header is correct. Then modify your `Subject:` (see <> for\n ++how to choose good title for your patch series):\n + \n + ----\n +-Subject: [PATCH 0/7] adding the 'psuh' command\n ++Subject: [PATCH 0/7] Add the 'psuh' command\n + ----\n + \n + Make sure you retain the ``[PATCH 0/X]'' part; that's what indicates to the Git\n +-community that this email is the beginning of a review, and many reviewers\n +-filter their email for this type of flag.\n ++community that this email is the beginning of a patch series, and many\n ++reviewers filter their email for this type of flag.\n + \n You'll need to add some extra parameters when you invoke `git send-email` to add\n the cover letter.\n \n @@ Documentation/MyFirstContribution.txt: filter their email for this type of flag.\n -This patchset is part of the MyFirstContribution tutorial and should not\n -be merged.\n -----\n -+Next you'll have to fill out the body of your cover letter.\n -+include::MyFirstContribution-coverletter.txt[]\n ++Next you'll have to fill out the body of your cover letter. Again, see\n ++<> for what content to include.\n \n The template created by `git format-patch --cover-letter` includes a diffstat.\n This gives reviewers a summary of what they're in for when reviewing your topic.\n 2: afb80b8e9ee ! 4: f6034b0964b MyFirstContribution: also explain cover letter in GitGitGadget section\n @@ Metadata\n Author: Philippe Blain \n \n ## Commit message ##\n - MyFirstContribution: also explain cover letter in GitGitGadget section\n + MyFirstContribution: reference \"The cover letter\" in GitGitGadget section\n \n The \"Sending Patches via GitGitGadget\" section mentions that the PR\n title and description will be used as the cover letter, but does not\n explain what is a cover letter or what should be included in it.\n \n - Mention the purpose of the cover letter in that section, and give\n - examples for the title and description, leveraging the excerpt extracted\n - from the \"Sending Patches with git send-email\" section in the previous\n + Refer readers to the new \"The cover letter\" section added in a previous\n commit.\n \n Signed-off-by: Philippe Blain \n @@ Documentation/MyFirstContribution.txt: https://github.com/gitgitgadget/git and o\n \n -Review the PR's title and description, as it's used by GitGitGadget as the cover\n -letter for your change. When you're happy, submit your pull request.\n -+Review the PR's title and description, as they're used by GitGitGadget as the\n -+cover letter for your change. The cover letter describes your proposed\n -+contribution as a whole and is ideal to mention any context that might be\n -+useful for reviewers. The title of your PR should be something which\n -+succinctly covers the purpose of your entire topic branch, for example:\n -+\n -+----\n -+Adding the 'psuh' command\n -+----\n -+\n -+Your PR's description will used as the body of the cover letter.\n -+include::MyFirstContribution-coverletter.txt[]\n ++Review the PR's title and description, as they're used by GitGitGadget\n ++respectively as the subject and body of the cover letter for your change. Refer\n ++to <> above for advice on how to title your\n ++submission and what content to include in the description.\n +\n +When you're happy, submit your pull request.\n \n 3: 2f6ecbf2601 ! 5: 33256c6b4ba MyFirstContribution: drop PR description for GGG single-patch contributions\n @@ Commit message\n Signed-off-by: Philippe Blain \n \n ## Documentation/MyFirstContribution.txt ##\n -@@ Documentation/MyFirstContribution.txt: Adding the 'psuh' command\n - Your PR's description will used as the body of the cover letter.\n - include::MyFirstContribution-coverletter.txt[]\n +@@ Documentation/MyFirstContribution.txt: respectively as the subject and body of the cover letter for your change. Refer\n + to <> above for advice on how to title your\n + submission and what content to include in the description.\n \n +NOTE: For single-patch contributions, your commit message should already be\n +meaningful and explain at a high level the purpose (what is happening and why)\n @@ Documentation/MyFirstContribution.txt: Adding the 'psuh' command\n +remove the PR description that GitHub automatically generates from your commit\n +message (your PR description should be empty). If you do need to supply even\n +more context, you can do so in that space and it will be appended to the email\n -+that GitGitGadget will send, separately from your commit message.\n ++that GitGitGadget will send, between the three-dash line and the diffstat\n ++(see <> for how this looks once\n ++submitted).\n +\n When you're happy, submit your pull request.\n \n\n-- \ngitgitgadget\n"},{"id":"455145","messageId":"59af7e5e5ad84103b39ac9511791eb06b88df3c6.1652233654.git.gitgitgadget@gmail.com","threadId":"57807","inReplyTo":"pull.1226.v2.git.1652233654.gitgitgadget@gmail.com","subject":"[PATCH v2 1/5] MyFirstContribution: add \"Anatomy of a Patch Series\" section","fromName":"Philippe Blain via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-05-11T01:47:30Z","receivedAt":"2022-05-11T01:47:49Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"From: Philippe Blain \n\nBefore describing how to send patches to the mailing list either with\nGitGitGadget or 'git send-email', the MyFirstContribution tutorial\nincludes a small \"Getting Ready to Share\" section where the two\ndifferent methods are briefly introduced.\n\nUse this section to also describe what a patch series looks like once\nsubmitted, so that readers get an understanding of the end result before\ndiving into how to accomplish that end result.\n\nStart by copying the \"thread overview\" section of a recent contribution\nfrom the public-inbox web UI and explaining how each commit is a\nseparate mail, and point out the cover letter.\n\nSubsequent commits will move the existing description of the purpose of\nthe cover letter from the 'git send-email' section to this \"anatomy\"\nsection.\n\nAlso, change the wording in the introductory paragraph to use\n\"contributions\" instead of \"patches\", since this makes more sense when\ntalking about GitHub pull requests.\n\nSigned-off-by: Philippe Blain \n---\n Documentation/MyFirstContribution.txt | 54 +++++++++++++++++++++++++--\n 1 file changed, 51 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt\nindex 63a2ef54493..22848f84bec 100644\n--- a/Documentation/MyFirstContribution.txt\n+++ b/Documentation/MyFirstContribution.txt\n@@ -710,13 +710,61 @@ dependencies. `prove` also makes the output nicer.\n Go ahead and commit this change, as well.\n \n [[ready-to-share]]\n-== Getting Ready to Share\n+== Getting Ready to Share: Anatomy of a Patch Series\n \n You may have noticed already that the Git project performs its code reviews via\n emailed patches, which are then applied by the maintainer when they are ready\n-and approved by the community. The Git project does not accept patches from\n+and approved by the community. The Git project does not accept contributions from\n pull requests, and the patches emailed for review need to be formatted a\n-specific way. At this point the tutorial diverges, in order to demonstrate two\n+specific way.\n+\n+:patch-series: https://lore.kernel.org/git/pull.1218.git.git.1645209647.gitgitgadget@gmail.com/\n+:lore: https://lore.kernel.org/git/\n+\n+Before taking a look at how to convert your commits into emailed patches,\n+let's analyze what the end result, a \"patch series\", looks like. Here is an\n+{patch-series}[example] of the summary view for a patch series on the web interface of\n+the {lore}[Git mailing list archive]:\n+\n+----\n+2022-02-18 18:40 [PATCH 0/3] libify reflog John Cai via GitGitGadget\n+2022-02-18 18:40 ` [PATCH 1/3] reflog: libify delete reflog function and helpers John Cai via GitGitGadget\n+2022-02-18 19:10 ` Ævar Arnfjörð Bjarmason [this message]\n+2022-02-18 19:39 ` Taylor Blau\n+2022-02-18 19:48 ` Ævar Arnfjörð Bjarmason\n+2022-02-18 19:35 ` Taylor Blau\n+2022-02-21 1:43 ` John Cai\n+2022-02-21 1:50 ` Taylor Blau\n+2022-02-23 19:50 ` John Cai\n+2022-02-18 20:00 ` // other replies ellided\n+2022-02-18 18:40 ` [PATCH 2/3] reflog: call reflog_delete from reflog.c John Cai via GitGitGadget\n+2022-02-18 19:15 ` Ævar Arnfjörð Bjarmason\n+2022-02-18 20:26 ` Junio C Hamano\n+2022-02-18 18:40 ` [PATCH 3/3] stash: call reflog_delete from reflog.c John Cai via GitGitGadget\n+2022-02-18 19:20 ` Ævar Arnfjörð Bjarmason\n+2022-02-19 0:21 ` Taylor Blau\n+2022-02-22 2:36 ` John Cai\n+2022-02-22 10:51 ` Ævar Arnfjörð Bjarmason\n+2022-02-18 19:29 ` [PATCH 0/3] libify reflog Ævar Arnfjörð Bjarmason\n+2022-02-22 18:30 ` [PATCH v2 0/3] libify reflog John Cai via GitGitGadget\n+2022-02-22 18:30 ` [PATCH v2 1/3] stash: add test to ensure reflog --rewrite --updatref behavior John Cai via GitGitGadget\n+2022-02-23 8:54 ` Ævar Arnfjörð Bjarmason\n+2022-02-23 21:27 ` Junio C Hamano\n+// continued\n+----\n+\n+We can note a few things:\n+\n+- Each commit is sent as a separate email, with the commit message title as\n+ subject, prefixed with \"[PATCH _i_/_n_]\" for the _i_-th commit of an\n+ _n_-commit series.\n+- Each patch is sent as a reply to an introductory email called the _cover\n+ letter_ of the series, prefixed \"[PATCH 0/_n_]\".\n+- Subsequent iterations of the patch series are labelled \"[PATCH v2]\", \"[PATCH\n+ v3]\", etc. and sent with a new cover letter, itself a reply to the cover\n+ letter of the previous iteration (more on that below).\n+\n+At this point the tutorial diverges, in order to demonstrate two\n different methods of formatting your patchset and getting it reviewed.\n \n The first method to be covered is GitGitGadget, which is useful for those\n-- \ngitgitgadget\n\n"},{"id":"455146","messageId":"9552d80a80d9574c8f256696fad06f48b39b51c9.1652233654.git.gitgitgadget@gmail.com","threadId":"57807","inReplyTo":"pull.1226.v2.git.1652233654.gitgitgadget@gmail.com","subject":"[PATCH v2 2/5] MyFirstContribution: add standalone section on cover letter","fromName":"Philippe Blain via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-05-11T01:47:31Z","receivedAt":"2022-05-11T01:47:52Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"From: Philippe Blain \n\nAn explanation of the purpose of the cover letter is included in the\n\"Sending Patches with git send-email\" / \"Preparing Email\" section but is\nmissing from the \"Sending Patches via GitGitGadget\" section.\n\nAdd a standalone section \"The cover letter\" under the \"Getting Started:\nAnatomy of a Patch Series\" header to explain what the cover letter is\nused for and to draft the cover letter of the 'psuh' topic used in the\ntutorial.\n\nFor now we mostly copy content from the \"Sending Patches with git\nsend-email\" section but do not adjust that section, nor the GGG section,\nto reference the new section. This is done in following commits.\n\nAlso, adjust the \"Preparing Email\" Asciidoc anchor to avoid conflicts.\n\nSigned-off-by: Philippe Blain \n---\n Documentation/MyFirstContribution.txt | 39 ++++++++++++++++++++++++++-\n 1 file changed, 38 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt\nindex 22848f84bec..de62a61771c 100644\n--- a/Documentation/MyFirstContribution.txt\n+++ b/Documentation/MyFirstContribution.txt\n@@ -764,6 +764,43 @@ We can note a few things:\n v3]\", etc. and sent with a new cover letter, itself a reply to the cover\n letter of the previous iteration (more on that below).\n \n+[[cover-letter]]\n+=== The cover letter\n+\n+In addition to an email per patch, the Git community also expects your patches\n+to come with a cover letter. This is an important component of change\n+submission as it explains to the community from a high level what you're trying\n+to do, and why, in a way that's more apparent than just looking at your\n+patches.\n+\n+The title of your cover letter should be something which succinctly covers the\n+purpose of your entire topic branch. It's often in the imperative mood, just\n+like our commit message titles. Here is how we'll title our series:\n+\n+---\n+Add the 'psuh' command\n+---\n+\n+The body of the cover letter is used to give additional context to reviewers.\n+Be sure to explain anything your patches don't make clear on their own, but\n+remember that since the cover letter is not recorded in the commit history,\n+anything that might be useful to future readers of the repository's history\n+should be in your commit messages, not in your cover letter.\n+\n+Here's an example body for `psuh`:\n+\n+----\n+Our internal metrics indicate widespread interest in the command\n+git-psuh - that is, many users are trying to use it, but finding it is\n+unavailable, using some unknown workaround instead.\n+\n+The following handful of patches add the psuh command and implement some\n+handy features on top of it.\n+\n+This patchset is part of the MyFirstContribution tutorial and should not\n+be merged.\n+----\n+\n At this point the tutorial diverges, in order to demonstrate two\n different methods of formatting your patchset and getting it reviewed.\n \n@@ -1000,7 +1037,7 @@ but want reviewers to look at what they have so far. You can add this flag with\n Check and make sure that your patches and cover letter template exist in the\n directory you specified - you're nearly ready to send out your review!\n \n-[[cover-letter]]\n+[[preparing-cover-letter]]\n === Preparing Email\n \n In addition to an email per patch, the Git community also expects your patches\n-- \ngitgitgadget\n\n"},{"id":"455147","messageId":"d7699289ea61f71aa869e491c7a35d067dc57115.1652233654.git.gitgitgadget@gmail.com","threadId":"57807","inReplyTo":"pull.1226.v2.git.1652233654.gitgitgadget@gmail.com","subject":"[PATCH v2 3/5] MyFirstContribution: reference \"The cover letter\" in \"Preparing Email\"","fromName":"Philippe Blain via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-05-11T01:47:32Z","receivedAt":"2022-05-11T01:48:01Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"From: Philippe Blain \n\nThe previous commit added a standalone section on the purpose of the\ncover letter, drawing inspiration from the existing content of the\n\"Preparing Email\" section.\n\nAdjust \"Preparing Email\" to reference \"The cover letter\", to avoid\ncontent duplication.\n\nAlso, use the imperative mode for the cover letter subject, as is done\nin \"The cover letter\".\n\nSigned-off-by: Philippe Blain \n---\n Documentation/MyFirstContribution.txt | 38 +++++++--------------------\n 1 file changed, 9 insertions(+), 29 deletions(-)\n\ndiff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt\nindex de62a61771c..078b96d674a 100644\n--- a/Documentation/MyFirstContribution.txt\n+++ b/Documentation/MyFirstContribution.txt\n@@ -1040,46 +1040,26 @@ directory you specified - you're nearly ready to send out your review!\n [[preparing-cover-letter]]\n === Preparing Email\n \n-In addition to an email per patch, the Git community also expects your patches\n-to come with a cover letter, typically with a subject line [PATCH 0/x] (where\n-x is the number of patches you're sending). Since you invoked `format-patch`\n-with `--cover-letter`, you've already got a template ready. Open it up in your\n-favorite editor.\n+Since you invoked `format-patch` with `--cover-letter`, you've already got a\n+cover letter template ready. Open it up in your favorite editor.\n \n You should see a number of headers present already. Check that your `From:`\n-header is correct. Then modify your `Subject:` to something which succinctly\n-covers the purpose of your entire topic branch, for example:\n+header is correct. Then modify your `Subject:` (see <> for\n+how to choose good title for your patch series):\n \n ----\n-Subject: [PATCH 0/7] adding the 'psuh' command\n+Subject: [PATCH 0/7] Add the 'psuh' command\n ----\n \n Make sure you retain the ``[PATCH 0/X]'' part; that's what indicates to the Git\n-community that this email is the beginning of a review, and many reviewers\n-filter their email for this type of flag.\n+community that this email is the beginning of a patch series, and many\n+reviewers filter their email for this type of flag.\n \n You'll need to add some extra parameters when you invoke `git send-email` to add\n the cover letter.\n \n-Next you'll have to fill out the body of your cover letter. This is an important\n-component of change submission as it explains to the community from a high level\n-what you're trying to do, and why, in a way that's more apparent than just\n-looking at your diff. Be sure to explain anything your diff doesn't make clear\n-on its own.\n-\n-Here's an example body for `psuh`:\n-\n-----\n-Our internal metrics indicate widespread interest in the command\n-git-psuh - that is, many users are trying to use it, but finding it is\n-unavailable, using some unknown workaround instead.\n-\n-The following handful of patches add the psuh command and implement some\n-handy features on top of it.\n-\n-This patchset is part of the MyFirstContribution tutorial and should not\n-be merged.\n-----\n+Next you'll have to fill out the body of your cover letter. Again, see\n+<> for what content to include.\n \n The template created by `git format-patch --cover-letter` includes a diffstat.\n This gives reviewers a summary of what they're in for when reviewing your topic.\n-- \ngitgitgadget\n\n"},{"id":"455148","messageId":"33256c6b4bafe2a3993338a7499dfec52a02a9a0.1652233654.git.gitgitgadget@gmail.com","threadId":"57807","inReplyTo":"pull.1226.v2.git.1652233654.gitgitgadget@gmail.com","subject":"[PATCH v2 5/5] MyFirstContribution: drop PR description for GGG single-patch contributions","fromName":"Philippe Blain via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-05-11T01:47:34Z","receivedAt":"2022-05-11T01:48:03Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"From: Philippe Blain \n\nBy default, GitHub prefills the PR description using the commit message\nfor single-commit PRs. This results in a duplicate commit message below\nthe three-dash line if the contributor does not empty out the PR\ndescription before submitting, which adds noise for reviewers.\n\nAdd a note to that effect in MyFirstContribution.txt.\n\nThis partly addresses:\nhttps://github.com/gitgitgadget/gitgitgadget/issues/340\n\nSigned-off-by: Philippe Blain \n---\n Documentation/MyFirstContribution.txt | 10 ++++++++++\n 1 file changed, 10 insertions(+)\n\ndiff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt\nindex 728dc437854..01b9e5db117 100644\n--- a/Documentation/MyFirstContribution.txt\n+++ b/Documentation/MyFirstContribution.txt\n@@ -898,6 +898,16 @@ respectively as the subject and body of the cover letter for your change. Refer\n to <> above for advice on how to title your\n submission and what content to include in the description.\n \n+NOTE: For single-patch contributions, your commit message should already be\n+meaningful and explain at a high level the purpose (what is happening and why)\n+of your patch, so you usually do not need any additional context. In that case,\n+remove the PR description that GitHub automatically generates from your commit\n+message (your PR description should be empty). If you do need to supply even\n+more context, you can do so in that space and it will be appended to the email\n+that GitGitGadget will send, between the three-dash line and the diffstat\n+(see <> for how this looks once\n+submitted).\n+\n When you're happy, submit your pull request.\n \n [[run-ci-ggg]]\n-- \ngitgitgadget\n"},{"id":"455149","messageId":"f6034b0964b1e8cccd25f47aa01d51753672df31.1652233654.git.gitgitgadget@gmail.com","threadId":"57807","inReplyTo":"pull.1226.v2.git.1652233654.gitgitgadget@gmail.com","subject":"[PATCH v2 4/5] MyFirstContribution: reference \"The cover letter\" in GitGitGadget section","fromName":"Philippe Blain via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-05-11T01:47:33Z","receivedAt":"2022-05-11T01:48:08Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"From: Philippe Blain \n\nThe \"Sending Patches via GitGitGadget\" section mentions that the PR\ntitle and description will be used as the cover letter, but does not\nexplain what is a cover letter or what should be included in it.\n\nRefer readers to the new \"The cover letter\" section added in a previous\ncommit.\n\nSigned-off-by: Philippe Blain \n---\n Documentation/MyFirstContribution.txt | 8 ++++++--\n 1 file changed, 6 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt\nindex 078b96d674a..728dc437854 100644\n--- a/Documentation/MyFirstContribution.txt\n+++ b/Documentation/MyFirstContribution.txt\n@@ -893,8 +893,12 @@ https://github.com/gitgitgadget/git and open a PR either with the \"New pull\n request\" button or the convenient \"Compare & pull request\" button that may\n appear with the name of your newly pushed branch.\n \n-Review the PR's title and description, as it's used by GitGitGadget as the cover\n-letter for your change. When you're happy, submit your pull request.\n+Review the PR's title and description, as they're used by GitGitGadget\n+respectively as the subject and body of the cover letter for your change. Refer\n+to <> above for advice on how to title your\n+submission and what content to include in the description.\n+\n+When you're happy, submit your pull request.\n \n [[run-ci-ggg]]\n === Running CI and Getting Ready to Send\n-- \ngitgitgadget\n\n"},{"id":"455152","messageId":"YntVo0G8G2mQYCLZ@debian.me","threadId":"57807","inReplyTo":"59af7e5e5ad84103b39ac9511791eb06b88df3c6.1652233654.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 1/5] MyFirstContribution: add \"Anatomy of a Patch Series\" section","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2022-05-11T06:20:19Z","receivedAt":"2022-05-11T06:20:35Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"On Wed, May 11, 2022 at 01:47:30AM +0000, Philippe Blain via GitGitGadget wrote:\n> +We can note a few things:\n> +\n> +- Each commit is sent as a separate email, with the commit message title as\n> + subject, prefixed with \"[PATCH _i_/_n_]\" for the _i_-th commit of an\n> + _n_-commit series.\n> +- Each patch is sent as a reply to an introductory email called the _cover\n> + letter_ of the series, prefixed \"[PATCH 0/_n_]\".\n> +- Subsequent iterations of the patch series are labelled \"[PATCH v2]\", \"[PATCH\n> + v3]\", etc. and sent with a new cover letter, itself a reply to the cover\n> + letter of the previous iteration (more on that below).\n> +\n> +At this point the tutorial diverges, in order to demonstrate two\n> different methods of formatting your patchset and getting it reviewed.\n>\n\nIn case of single-patch series submissions, the anatomy is simple: first\nthe email subject is commit message title prefixed with \"[PATCH]\" or\n\"[PATCH v_n_]\" (in case of n-th iteration), then commit message and the\nactual diff.\n\nRegarding n-th iteration series, sometimes it is desirable to break the\nthreading so that the original thread (of previous iterations) doesn't\nget too long, by sending the series as completely new thread. Some\ncontributors (including myself) prefer that way. In that case, the link\nto previous iteration is provided to aid reviewers.\n\n-- \nAn old man doll... just what I always wanted! - Clara\n"},{"id":"455157","messageId":"xmqqa6boo0az.fsf@gitster.g","threadId":"57807","inReplyTo":"9552d80a80d9574c8f256696fad06f48b39b51c9.1652233654.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 2/5] MyFirstContribution: add standalone section on cover letter","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-05-11T10:01:24Z","receivedAt":"2022-05-11T10:02:10Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philippe Blain via GitGitGadget\" writes:\n\n> +The body of the cover letter is used to give additional context to reviewers.\n> +Be sure to explain anything your patches don't make clear on their own, but\n> +remember that since the cover letter is not recorded in the commit history,\n> +anything that might be useful to future readers of the repository's history\n> +should be in your commit messages, not in your cover letter.\n\nI agree with only a half of the last sentence.\n\nThings that are useful for \"git log\" readers should be in the commit\nmessage (but that goes without saying---by definition \"git log\"\nreaders are reading commit messages). If that material helps to\nunderstand the overall topic structure by the reviewers, it is not\nwrong to have that _also_ in your cover letter. IOW, I sense that\n\"not in your cover letter\" is a bit too strong.\n\nOther than that, I found that 1/5 and 2/5 are very nicely written.\n\nThanks.\n\n"},{"id":"455158","messageId":"xmqq4k1wnzub.fsf@gitster.g","threadId":"57807","inReplyTo":"pull.1226.v2.git.1652233654.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 0/5] Improve MyFirstContribution's GitGitGadget section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-05-11T10:11:24Z","receivedAt":"2022-05-11T10:11:46Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philippe Blain via GitGitGadget\" writes:\n\n> Thanks a lot for the reviews! Here is an updated version.\n\nThanks a lot for the patches. I made a small comment or two, but\nother than those, everything looked good.\n\nWill queue.\n"},{"id":"455169","messageId":"becf5e06-ddd3-62af-5b85-3e4ce8a4017f@github.com","threadId":"57807","inReplyTo":"pull.1226.v2.git.1652233654.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 0/5] Improve MyFirstContribution's GitGitGadget section","fromName":"Victoria Dye","fromEmail":"vdye@github.com","sentAt":"2022-05-11T17:45:05Z","receivedAt":"2022-05-11T17:45:13Z","isPatch":true,"sender":{"key":"vdye@github.com","avatar":"https://avatars.githubusercontent.com/u/3619353?v=4"},"body":"Philippe Blain via GitGitGadget wrote:\n> Thanks a lot for the reviews! Here is an updated version.\n> \n> Changes since v1:\n> \n> * Based on v1 feedback, instead of reusing the 'git send-email' content\n> verbatim in the GGG section, added a new section and reference it in both\n> 'git send-email' and GGG sections. (patches 1/5-4/5)\n> * In patch 5/5 (patch 3/3 in v1), tweak wording and add a reference to the\n> \"Bonus Chapter: One-Patch Changes\" section.\n> \n\nThis version addresses all of my earlier comments, and overall looks good to\nme. Thanks again for updating this documentation!\n\n> v1: Two small improvements to the MyFirstContribution tutorial:\n> \n> * Describe the purpose of the cover letter in that section also, and give\n> an example just as in the 'git send-email' section\n> * Instruct contributors to drop the GitHub-generated PR description for\n> single patch contributions.\n> \n> Philippe Blain (5):\n> MyFirstContribution: add \"Anatomy of a Patch Series\" section\n> MyFirstContribution: add standalone section on cover letter\n> MyFirstContribution: reference \"The cover letter\" in \"Preparing Email\"\n> MyFirstContribution: reference \"The cover letter\" in GitGitGadget\n> section\n> MyFirstContribution: drop PR description for GGG single-patch\n> contributions\n> \n> Documentation/MyFirstContribution.txt | 149 ++++++++++++++++++++------\n> 1 file changed, 114 insertions(+), 35 deletions(-)\n> \n> \n> base-commit: 6cd33dceed60949e2dbc32e3f0f5e67c4c882e1e\n> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1226%2Fphil-blain%2Fmyfirst-contrib-single-patch-ggg-v2\n> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1226/phil-blain/myfirst-contrib-single-patch-ggg-v2\n> Pull-Request: https://github.com/gitgitgadget/git/pull/1226\n> \n> Range-diff vs v1:\n> \n> -: ----------- > 1: 59af7e5e5ad MyFirstContribution: add \"Anatomy of a Patch Series\" section\n> -: ----------- > 2: 9552d80a80d MyFirstContribution: add standalone section on cover letter\n> 1: 7e84d5b286d ! 3: d7699289ea6 MyFirstContribution: move cover letter description to a separate file\n> @@ Metadata\n> Author: Philippe Blain \n> \n> ## Commit message ##\n> - MyFirstContribution: move cover letter description to a separate file\n> + MyFirstContribution: reference \"The cover letter\" in \"Preparing Email\"\n> \n> - In a subsequent commit we want to reuse the explanation of the purpose of\n> - The cover letter form the \"Sending Patches with git send-email\" section\n> - in the \"Sending Patches via GitGitGadget\" section.\n> + The previous commit added a standalone section on the purpose of the\n> + cover letter, drawing inspiration from the existing content of the\n> + \"Preparing Email\" section.\n> \n> - To avoid text duplication, move this explanation to a separate file and\n> - include it in MyFirstContribution.txt.\n> + Adjust \"Preparing Email\" to reference \"The cover letter\", to avoid\n> + content duplication.\n> \n> - Signed-off-by: Philippe Blain \n> + Also, use the imperative mode for the cover letter subject, as is done\n> + in \"The cover letter\".\n> \n> - ## Documentation/MyFirstContribution-coverletter.txt (new) ##\n> -@@\n> -+This is an important component of change submission as it explains to the\n> -+community from a high level what you're trying to do, and why, in a way that's\n> -+more apparent than just looking at your diff. Be sure to explain anything your\n> -+diff doesn't make clear on its own.\n> -+\n> -+Here's an example body for `psuh`:\n> -+\n> -+----\n> -+Our internal metrics indicate widespread interest in the command\n> -+git-psuh - that is, many users are trying to use it, but finding it is\n> -+unavailable, using some unknown workaround instead.\n> -+\n> -+The following handful of patches add the psuh command and implement some\n> -+handy features on top of it.\n> -+\n> -+This patchset is part of the MyFirstContribution tutorial and should not\n> -+be merged.\n> -+----\n> + Signed-off-by: Philippe Blain \n> \n> ## Documentation/MyFirstContribution.txt ##\n> -@@ Documentation/MyFirstContribution.txt: filter their email for this type of flag.\n> +@@ Documentation/MyFirstContribution.txt: directory you specified - you're nearly ready to send out your review!\n> + [[preparing-cover-letter]]\n> + === Preparing Email\n> + \n> +-In addition to an email per patch, the Git community also expects your patches\n> +-to come with a cover letter, typically with a subject line [PATCH 0/x] (where\n> +-x is the number of patches you're sending). Since you invoked `format-patch`\n> +-with `--cover-letter`, you've already got a template ready. Open it up in your\n> +-favorite editor.\n> ++Since you invoked `format-patch` with `--cover-letter`, you've already got a\n> ++cover letter template ready. Open it up in your favorite editor.\n> + \n> + You should see a number of headers present already. Check that your `From:`\n> +-header is correct. Then modify your `Subject:` to something which succinctly\n> +-covers the purpose of your entire topic branch, for example:\n> ++header is correct. Then modify your `Subject:` (see <> for\n> ++how to choose good title for your patch series):\n> + \n> + ----\n> +-Subject: [PATCH 0/7] adding the 'psuh' command\n> ++Subject: [PATCH 0/7] Add the 'psuh' command\n> + ----\n> + \n> + Make sure you retain the ``[PATCH 0/X]'' part; that's what indicates to the Git\n> +-community that this email is the beginning of a review, and many reviewers\n> +-filter their email for this type of flag.\n> ++community that this email is the beginning of a patch series, and many\n> ++reviewers filter their email for this type of flag.\n> + \n> You'll need to add some extra parameters when you invoke `git send-email` to add\n> the cover letter.\n> \n> @@ Documentation/MyFirstContribution.txt: filter their email for this type of flag.\n> -This patchset is part of the MyFirstContribution tutorial and should not\n> -be merged.\n> -----\n> -+Next you'll have to fill out the body of your cover letter.\n> -+include::MyFirstContribution-coverletter.txt[]\n> ++Next you'll have to fill out the body of your cover letter. Again, see\n> ++<> for what content to include.\n> \n> The template created by `git format-patch --cover-letter` includes a diffstat.\n> This gives reviewers a summary of what they're in for when reviewing your topic.\n> 2: afb80b8e9ee ! 4: f6034b0964b MyFirstContribution: also explain cover letter in GitGitGadget section\n> @@ Metadata\n> Author: Philippe Blain \n> \n> ## Commit message ##\n> - MyFirstContribution: also explain cover letter in GitGitGadget section\n> + MyFirstContribution: reference \"The cover letter\" in GitGitGadget section\n> \n> The \"Sending Patches via GitGitGadget\" section mentions that the PR\n> title and description will be used as the cover letter, but does not\n> explain what is a cover letter or what should be included in it.\n> \n> - Mention the purpose of the cover letter in that section, and give\n> - examples for the title and description, leveraging the excerpt extracted\n> - from the \"Sending Patches with git send-email\" section in the previous\n> + Refer readers to the new \"The cover letter\" section added in a previous\n> commit.\n> \n> Signed-off-by: Philippe Blain \n> @@ Documentation/MyFirstContribution.txt: https://github.com/gitgitgadget/git and o\n> \n> -Review the PR's title and description, as it's used by GitGitGadget as the cover\n> -letter for your change. When you're happy, submit your pull request.\n> -+Review the PR's title and description, as they're used by GitGitGadget as the\n> -+cover letter for your change. The cover letter describes your proposed\n> -+contribution as a whole and is ideal to mention any context that might be\n> -+useful for reviewers. The title of your PR should be something which\n> -+succinctly covers the purpose of your entire topic branch, for example:\n> -+\n> -+----\n> -+Adding the 'psuh' command\n> -+----\n> -+\n> -+Your PR's description will used as the body of the cover letter.\n> -+include::MyFirstContribution-coverletter.txt[]\n> ++Review the PR's title and description, as they're used by GitGitGadget\n> ++respectively as the subject and body of the cover letter for your change. Refer\n> ++to <> above for advice on how to title your\n> ++submission and what content to include in the description.\n> +\n> +When you're happy, submit your pull request.\n> \n> 3: 2f6ecbf2601 ! 5: 33256c6b4ba MyFirstContribution: drop PR description for GGG single-patch contributions\n> @@ Commit message\n> Signed-off-by: Philippe Blain \n> \n> ## Documentation/MyFirstContribution.txt ##\n> -@@ Documentation/MyFirstContribution.txt: Adding the 'psuh' command\n> - Your PR's description will used as the body of the cover letter.\n> - include::MyFirstContribution-coverletter.txt[]\n> +@@ Documentation/MyFirstContribution.txt: respectively as the subject and body of the cover letter for your change. Refer\n> + to <> above for advice on how to title your\n> + submission and what content to include in the description.\n> \n> +NOTE: For single-patch contributions, your commit message should already be\n> +meaningful and explain at a high level the purpose (what is happening and why)\n> @@ Documentation/MyFirstContribution.txt: Adding the 'psuh' command\n> +remove the PR description that GitHub automatically generates from your commit\n> +message (your PR description should be empty). If you do need to supply even\n> +more context, you can do so in that space and it will be appended to the email\n> -+that GitGitGadget will send, separately from your commit message.\n> ++that GitGitGadget will send, between the three-dash line and the diffstat\n> ++(see <> for how this looks once\n> ++submitted).\n> +\n> When you're happy, submit your pull request.\n> \n> \n\n"},{"id":"455175","messageId":"xmqqh75viwoo.fsf@gitster.g","threadId":"57807","inReplyTo":"YntVo0G8G2mQYCLZ@debian.me","subject":"Re: [PATCH v2 1/5] MyFirstContribution: add \"Anatomy of a Patch Series\" section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-05-11T21:30:47Z","receivedAt":"2022-05-11T21:31:10Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Bagas Sanjaya writes:\n\n> On Wed, May 11, 2022 at 01:47:30AM +0000, Philippe Blain via GitGitGadget wrote:\n>> +We can note a few things:\n>> +\n>> +- Each commit is sent as a separate email, with the commit message title as\n>> + subject, prefixed with \"[PATCH _i_/_n_]\" for the _i_-th commit of an\n>> + _n_-commit series.\n>> +- Each patch is sent as a reply to an introductory email called the _cover\n>> + letter_ of the series, prefixed \"[PATCH 0/_n_]\".\n>> +- Subsequent iterations of the patch series are labelled \"[PATCH v2]\", \"[PATCH\n>> + v3]\", etc. and sent with a new cover letter, itself a reply to the cover\n>> + letter of the previous iteration (more on that below).\n>> +\n>> +At this point the tutorial diverges, in order to demonstrate two\n>> different methods of formatting your patchset and getting it reviewed.\n>>\n>\n> In case of single-patch series submissions, the anatomy is simple: first\n> the email subject is commit message title prefixed with \"[PATCH]\" or\n> \"[PATCH v_n_]\" (in case of n-th iteration), then commit message and the\n> actual diff.\n\nCorrect. There is no single-patch topic in the summary view shown\nin the document, so it does not belong to the above \"We can note a\nfew things\" list. But I agree that there should be a mention for a\nsingle-patch topic somewhere in this document, both for a patch and\n(the usual lack of) cover-letter for such a topic.\n\nThe sample topic this tutorial uses is a multi-patch series and\neverything in the document revolves around handing a multi-patch\nseries, so finding a good place to fit it may be a bit tricky,\nthough.\n\n> Regarding n-th iteration series, sometimes it is desirable to break the\n> threading so that the original thread (of previous iterations) doesn't\n> get too long, by sending the series as completely new thread. Some\n> contributors (including myself) prefer that way. In that case, the link\n> to previous iteration is provided to aid reviewers.\n\nThis is often not very friendly to reviewers, unless the \"new topic\"\nis so different that it is almost totally unrelated to the old one.\n\nEven in a \"in earlier round, we perceived X as a problem and tried\nto solve it, but it turns out it is better to solve Y instead\" case,\nit often helps to learn the reason why we ended up not addressing X\nafter you use \"git blame\" to find a commit that solved Y in a later\niteration and wonder why an approach to solve X was not taken. It\nis a very good idea to mention the need to add a link to a previous\nthread if the submitter decides to break the thread.\n\nThanks.\n"},{"id":"455178","messageId":"9e766e57-3b6c-494e-84b6-406a91ccf6ea@gmail.com","threadId":"57807","inReplyTo":"xmqqh75viwoo.fsf@gitster.g","subject":"Re: [PATCH v2 1/5] MyFirstContribution: add \"Anatomy of a Patch Series\" section","fromName":"Philippe Blain","fromEmail":"levraiphilippeblain@gmail.com","sentAt":"2022-05-11T21:48:29Z","receivedAt":"2022-05-11T21:49:05Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"Hi Bagas and Junio,\n\nLe 2022-05-11 à 17:30, Junio C Hamano a écrit :\n> Bagas Sanjaya writes:\n> \n>> On Wed, May 11, 2022 at 01:47:30AM +0000, Philippe Blain via GitGitGadget wrote:\n>>> +We can note a few things:\n>>> +\n>>> +- Each commit is sent as a separate email, with the commit message title as\n>>> + subject, prefixed with \"[PATCH _i_/_n_]\" for the _i_-th commit of an\n>>> + _n_-commit series.\n>>> +- Each patch is sent as a reply to an introductory email called the _cover\n>>> + letter_ of the series, prefixed \"[PATCH 0/_n_]\".\n>>> +- Subsequent iterations of the patch series are labelled \"[PATCH v2]\", \"[PATCH\n>>> + v3]\", etc. and sent with a new cover letter, itself a reply to the cover\n>>> + letter of the previous iteration (more on that below).\n>>> +\n>>> +At this point the tutorial diverges, in order to demonstrate two\n>>> different methods of formatting your patchset and getting it reviewed.\n>>>\n>>\n>> In case of single-patch series submissions, the anatomy is simple: first\n>> the email subject is commit message title prefixed with \"[PATCH]\" or\n>> \"[PATCH v_n_]\" (in case of n-th iteration), then commit message and the\n>> actual diff.\n> \n> Correct. There is no single-patch topic in the summary view shown\n> in the document, so it does not belong to the above \"We can note a\n> few things\" list. But I agree that there should be a mention for a\n> single-patch topic somewhere in this document, both for a patch and\n> (the usual lack of) cover-letter for such a topic.\n> \n> The sample topic this tutorial uses is a multi-patch series and\n> everything in the document revolves around handing a multi-patch\n> series, so finding a good place to fit it may be a bit tricky,\n> though.\n\nThere is already a small section on single-patch topics, at the end of\nthe 'git send-email' section [1]. And I add a link to it in the GGG\nsection in patch 5/5.\n\n[1] https://git-scm.com/docs/MyFirstContribution#single-patch\n\n>> Regarding n-th iteration series, sometimes it is desirable to break the\n>> threading so that the original thread (of previous iterations) doesn't\n>> get too long, by sending the series as completely new thread. Some\n>> contributors (including myself) prefer that way. In that case, the link\n>> to previous iteration is provided to aid reviewers.\n> \n> This is often not very friendly to reviewers, unless the \"new topic\"\n> is so different that it is almost totally unrelated to the old one.\n> \n> Even in a \"in earlier round, we perceived X as a problem and tried\n> to solve it, but it turns out it is better to solve Y instead\" case,\n> it often helps to learn the reason why we ended up not addressing X\n> after you use \"git blame\" to find a commit that solved Y in a later\n> iteration and wonder why an approach to solve X was not taken. It\n> is a very good idea to mention the need to add a link to a previous\n> thread if the submitter decides to break the thread.\n\nThanks for confirming. I think for a beginner tutorial like MyFirstContribution,\nwe should keep things simple, so I would leave the content as-is regarding threading.\nIf we ever revive the \"mailing list etiquette\" series, then I think we could add\nnotes regarding this kind of things.\n\nCheers,\nPhilippe.\n"},{"id":"455179","messageId":"a955b9f1-3e11-70c5-b390-a35b420d6835@gmail.com","threadId":"57807","inReplyTo":"xmqqa6boo0az.fsf@gitster.g","subject":"Re: [PATCH v2 2/5] MyFirstContribution: add standalone section on cover letter","fromName":"Philippe Blain","fromEmail":"levraiphilippeblain@gmail.com","sentAt":"2022-05-11T21:49:47Z","receivedAt":"2022-05-11T21:49:54Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"Hi Junio,\n\nLe 2022-05-11 à 06:01, Junio C Hamano a écrit :\n> \"Philippe Blain via GitGitGadget\" writes:\n> \n>> +The body of the cover letter is used to give additional context to reviewers.\n>> +Be sure to explain anything your patches don't make clear on their own, but\n>> +remember that since the cover letter is not recorded in the commit history,\n>> +anything that might be useful to future readers of the repository's history\n>> +should be in your commit messages, not in your cover letter.\n> \n> I agree with only a half of the last sentence.\n> \n> Things that are useful for \"git log\" readers should be in the commit\n> message (but that goes without saying---by definition \"git log\"\n> readers are reading commit messages). If that material helps to\n> understand the overall topic structure by the reviewers, it is not\n> wrong to have that _also_ in your cover letter. IOW, I sense that\n> \"not in your cover letter\" is a bit too strong.\n\nOK, I'll tweak that in a v3.\n\n> \n> Other than that, I found that 1/5 and 2/5 are very nicely written.\n\nThanks !:)\n"},{"id":"455180","messageId":"xmqq4k1viuwu.fsf@gitster.g","threadId":"57807","inReplyTo":"9e766e57-3b6c-494e-84b6-406a91ccf6ea@gmail.com","subject":"Re: [PATCH v2 1/5] MyFirstContribution: add \"Anatomy of a Patch Series\" section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-05-11T22:09:05Z","receivedAt":"2022-05-11T22:09:16Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philippe Blain writes:\n\n>> Bagas Sanjaya writes:\n>> \n>>> On Wed, May 11, 2022 at 01:47:30AM +0000, Philippe Blain via GitGitGadget wrote:\n>>>> +We can note a few things:\n>>>> +\n>>>> +- Each commit is sent as a separate email, with the commit message title as\n>>>> + subject, prefixed with \"[PATCH _i_/_n_]\" for the _i_-th commit of an\n>>>> + _n_-commit series.\n>>>> +- Each patch is sent as a reply to an introductory email called the _cover\n>>>> + letter_ of the series, prefixed \"[PATCH 0/_n_]\".\n>>>> +- Subsequent iterations of the patch series are labelled \"[PATCH v2]\", \"[PATCH\n>>>> + v3]\", etc. and sent with a new cover letter, itself a reply to the cover\n>>>> + letter of the previous iteration (more on that below).\n>>>> +\n>>>> +At this point the tutorial diverges, in order to demonstrate two\n>>>> different methods of formatting your patchset and getting it reviewed.\n>>>>\n>>>\n>>> In case of single-patch series submissions, the anatomy is simple: first\n>>> the email subject is commit message title prefixed with \"[PATCH]\" or\n>>> \"[PATCH v_n_]\" (in case of n-th iteration), then commit message and the\n>>> actual diff.\n>> \n>> Correct. There is no single-patch topic in the summary view shown\n>> in the document, so it does not belong to the above \"We can note a\n>> few things\" list. But I agree that there should be a mention for a\n>> single-patch topic somewhere in this document, both for a patch and\n>> (the usual lack of) cover-letter for such a topic.\n>> \n>> The sample topic this tutorial uses is a multi-patch series and\n>> everything in the document revolves around handing a multi-patch\n>> series, so finding a good place to fit it may be a bit tricky,\n>> though.\n>\n> There is already a small section on single-patch topics, at the end of\n> the 'git send-email' section [1]. And I add a link to it in the GGG\n> section in patch 5/5.\n>\n> [1] https://git-scm.com/docs/MyFirstContribution#single-patch\n\nYup, I was wondering if there is an easy way to move it to this\nsection, which imparts a knowledge common across different method of\npatch submission. If we can do so somewhere nearby, it would be\nideal. Perhaps in \"We can note a few things\" list or as a side note\nimmediately after the list, we can add\n\n - A single-patch topic is sent with \"[PATCH]\", \"[PATCH v2]\",\n etc. without _i_/_n_ numbering (in the above thread overview,\n no single-patch topic appears, though).\n\nOr we can redo the lore screenshot to include such a topic, perhaps,\nthen we can lose the comment in the parentheses.\n\nThat reminds me of one small bug in your patch, where it says\n\n>>>> +- Subsequent iterations of the patch series are labelled \"[PATCH v2]\", \"[PATCH\n>>>> + v3]\", etc. and sent with a new cover letter, itself a reply to the cover\n>>>> + letter of the previous iteration (more on that below).\n\n Subsequent interations of the patches and the cover letter use\n \"PATCH v2\", \"PATCH v3\", etc. in place of \"PATCH\". \"[PATCH v2\n 1/3]\" would be the first of three patches in the second\n iteration, for example, and replies to \"[PATCH v2 0/3]\" which is\n the cover letter for the iteration, which in turn replies to the\n cover letter of the first iteration.\n\nThanks.\n"},{"id":"455193","messageId":"a901e47d-79cd-8d23-8c6c-de6299716eca@iee.email","threadId":"57807","inReplyTo":"59af7e5e5ad84103b39ac9511791eb06b88df3c6.1652233654.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 1/5] MyFirstContribution: add \"Anatomy of a Patch Series\" section","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2022-05-12T12:11:11Z","receivedAt":"2022-05-12T12:11:24Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"On 11/05/2022 02:47, Philippe Blain via GitGitGadget wrote:\n> diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt\n> index 63a2ef54493..22848f84bec 100644\n> --- a/Documentation/MyFirstContribution.txt\n> +++ b/Documentation/MyFirstContribution.txt\n> @@ -710,13 +710,61 @@ dependencies. `prove` also makes the output nicer.\n> Go ahead and commit this change, as well.\n> \n> [[ready-to-share]]\n> -== Getting Ready to Share\n> +== Getting Ready to Share: Anatomy of a Patch Series\nShouldn't the title also include the magic word 'Contribution'? \nOtherwise the change below may look inconsistent.\n\n> You may have noticed already that the Git project performs its code reviews via\n> emailed patches, which are then applied by the maintainer when they are ready\n> -and approved by the community. The Git project does not accept patches from\n> +and approved by the community. The Git project does not accept contributions from\n--\nPhilip\n"},{"id":"455235","messageId":"bc0e05b4-f185-5aa2-ee3a-cb7278fa6ab9@gmail.com","threadId":"57807","inReplyTo":"a901e47d-79cd-8d23-8c6c-de6299716eca@iee.email","subject":"Re: [PATCH v2 1/5] MyFirstContribution: add \"Anatomy of a Patch Series\" section","fromName":"Philippe Blain","fromEmail":"levraiphilippeblain@gmail.com","sentAt":"2022-05-12T22:53:28Z","receivedAt":"2022-05-12T22:53:34Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"Hi Philip,\n\nLe 2022-05-12 à 08:11, Philip Oakley a écrit :\n> On 11/05/2022 02:47, Philippe Blain via GitGitGadget wrote:\n>> diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt\n>> index 63a2ef54493..22848f84bec 100644\n>> --- a/Documentation/MyFirstContribution.txt\n>> +++ b/Documentation/MyFirstContribution.txt\n>> @@ -710,13 +710,61 @@ dependencies. `prove` also makes the output nicer.\n>>   Go ahead and commit this change, as well.\n>>     [[ready-to-share]]\n>> -== Getting Ready to Share\n>> +== Getting Ready to Share: Anatomy of a Patch Series\n> Shouldn't the title also include the magic word 'Contribution'? Otherwise the change below may look inconsistent.\n\nI don't think so. This section is to introduce \"what is a patch series\"\nto readers that might be reading the word \"patch\" in a software development context\nfor the very first time. Patch series are how Git is developped, so the title here should\ninclude these words, I think.\n\n> \n>>   You may have noticed already that the Git project performs its code reviews via\n>>   emailed patches, which are then applied by the maintainer when they are ready\n>> -and approved by the community. The Git project does not accept patches from\n>> +and approved by the community. The Git project does not accept contributions from\n\nthe next two words of this sentence are \"from pull requests\". People that are familiar\nwith GitHub will probably have heard \"contributions\" in the context of GitHub \"pull requests\",\nbut maybe not \"patches\". So that's why I changed the wording here.\n\nThank you for your comments,\n\nPhilippe.\n"},{"id":"455236","messageId":"2507aeec-b2bf-cba0-e36c-994d1cbbbac9@gmail.com","threadId":"57807","inReplyTo":"xmqq4k1viuwu.fsf@gitster.g","subject":"Re: [PATCH v2 1/5] MyFirstContribution: add \"Anatomy of a Patch Series\" section","fromName":"Philippe Blain","fromEmail":"levraiphilippeblain@gmail.com","sentAt":"2022-05-12T23:00:31Z","receivedAt":"2022-05-12T23:00:40Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"Hi Junio,\n\nLe 2022-05-11 à 18:09, Junio C Hamano a écrit :\n> Philippe Blain writes:\n> \n>>> Bagas Sanjaya writes:\n>>>\n>>>> On Wed, May 11, 2022 at 01:47:30AM +0000, Philippe Blain via GitGitGadget wrote:\n>>>>> +We can note a few things:\n>>>>> +\n>>>>> +- Each commit is sent as a separate email, with the commit message title as\n>>>>> + subject, prefixed with \"[PATCH _i_/_n_]\" for the _i_-th commit of an\n>>>>> + _n_-commit series.\n>>>>> +- Each patch is sent as a reply to an introductory email called the _cover\n>>>>> + letter_ of the series, prefixed \"[PATCH 0/_n_]\".\n>>>>> +- Subsequent iterations of the patch series are labelled \"[PATCH v2]\", \"[PATCH\n>>>>> + v3]\", etc. and sent with a new cover letter, itself a reply to the cover\n>>>>> + letter of the previous iteration (more on that below).\n>>>>> +\n>>>>> +At this point the tutorial diverges, in order to demonstrate two\n>>>>> different methods of formatting your patchset and getting it reviewed.\n>>>>>\n>>>>\n>>>> In case of single-patch series submissions, the anatomy is simple: first\n>>>> the email subject is commit message title prefixed with \"[PATCH]\" or\n>>>> \"[PATCH v_n_]\" (in case of n-th iteration), then commit message and the\n>>>> actual diff.\n>>>\n>>> Correct. There is no single-patch topic in the summary view shown\n>>> in the document, so it does not belong to the above \"We can note a\n>>> few things\" list. But I agree that there should be a mention for a\n>>> single-patch topic somewhere in this document, both for a patch and\n>>> (the usual lack of) cover-letter for such a topic.\n>>>\n>>> The sample topic this tutorial uses is a multi-patch series and\n>>> everything in the document revolves around handing a multi-patch\n>>> series, so finding a good place to fit it may be a bit tricky,\n>>> though.\n>>\n>> There is already a small section on single-patch topics, at the end of\n>> the 'git send-email' section [1]. And I add a link to it in the GGG\n>> section in patch 5/5.\n>>\n>> [1] https://git-scm.com/docs/MyFirstContribution#single-patch\n> \n> Yup, I was wondering if there is an easy way to move it to this\n> section, which imparts a knowledge common across different method of\n> patch submission. If we can do so somewhere nearby, it would be\n> ideal. Perhaps in \"We can note a few things\" list or as a side note\n> immediately after the list, we can add\n> \n> - A single-patch topic is sent with \"[PATCH]\", \"[PATCH v2]\",\n> etc. without _i_/_n_ numbering (in the above thread overview,\n> no single-patch topic appears, though).\n> \n> Or we can redo the lore screenshot to include such a topic, perhaps,\n> then we can lose the comment in the parentheses.\n\nOK, a little side note sounds good.\n\n> That reminds me of one small bug in your patch, where it says\n> \n>>>>> +- Subsequent iterations of the patch series are labelled \"[PATCH v2]\", \"[PATCH\n>>>>> + v3]\", etc. and sent with a new cover letter, itself a reply to the cover\n>>>>> + letter of the previous iteration (more on that below).\n> \n> Subsequent interations of the patches and the cover letter use\n> \"PATCH v2\", \"PATCH v3\", etc. in place of \"PATCH\". \"[PATCH v2\n> 1/3]\" would be the first of three patches in the second\n> iteration, for example, and replies to \"[PATCH v2 0/3]\" which is\n> the cover letter for the iteration, which in turn replies to the\n> cover letter of the first iteration.\n\nOK, I will add more details along these lines.\n"},{"id":"455239","messageId":"pull.1226.v3.git.1652399017.gitgitgadget@gmail.com","threadId":"57807","inReplyTo":"pull.1226.v2.git.1652233654.gitgitgadget@gmail.com","subject":"[PATCH v3 0/5] Improve MyFirstContribution's GitGitGadget section","fromName":"Philippe Blain via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-05-12T23:43:32Z","receivedAt":"2022-05-12T23:43:49Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"Changes since v2:\n\n * tweaked 2/5 following Junio's comments (added more details, tweaked the\n wording and added a note about single patch series).\n\nv2: Thanks a lot for the reviews! Here is an updated version.\n\nChanges since v1:\n\n * Based on v1 feedback, instead of reusing the 'git send-email' content\n verbatim in the GGG section, added a new section and reference it in both\n 'git send-email' and GGG sections. (patches 1/5-4/5)\n * In patch 5/5 (patch 3/3 in v1), tweak wording and add a reference to the\n \"Bonus Chapter: One-Patch Changes\" section.\n\nv1: Two small improvements to the MyFirstContribution tutorial:\n\n * Describe the purpose of the cover letter in that section also, and give\n an example just as in the 'git send-email' section\n * Instruct contributors to drop the GitHub-generated PR description for\n single patch contributions.\n\nPhilippe Blain (5):\n MyFirstContribution: add \"Anatomy of a Patch Series\" section\n MyFirstContribution: add standalone section on cover letter\n MyFirstContribution: reference \"The cover letter\" in \"Preparing Email\"\n MyFirstContribution: reference \"The cover letter\" in GitGitGadget\n section\n MyFirstContribution: drop PR description for GGG single-patch\n contributions\n\n Documentation/MyFirstContribution.txt | 155 ++++++++++++++++++++------\n 1 file changed, 120 insertions(+), 35 deletions(-)\n\n\nbase-commit: 6cd33dceed60949e2dbc32e3f0f5e67c4c882e1e\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1226%2Fphil-blain%2Fmyfirst-contrib-single-patch-ggg-v3\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1226/phil-blain/myfirst-contrib-single-patch-ggg-v3\nPull-Request: https://github.com/gitgitgadget/git/pull/1226\n\nRange-diff vs v2:\n\n 1: 59af7e5e5ad = 1: 59af7e5e5ad MyFirstContribution: add \"Anatomy of a Patch Series\" section\n 2: 9552d80a80d ! 2: ee3238f5a91 MyFirstContribution: add standalone section on cover letter\n @@ Commit message\n \n ## Documentation/MyFirstContribution.txt ##\n @@ Documentation/MyFirstContribution.txt: We can note a few things:\n - v3]\", etc. and sent with a new cover letter, itself a reply to the cover\n - letter of the previous iteration (more on that below).\n - \n + _n_-commit series.\n + - Each patch is sent as a reply to an introductory email called the _cover\n + letter_ of the series, prefixed \"[PATCH 0/_n_]\".\n +-- Subsequent iterations of the patch series are labelled \"[PATCH v2]\", \"[PATCH\n +- v3]\", etc. and sent with a new cover letter, itself a reply to the cover\n +- letter of the previous iteration (more on that below).\n ++- Subsequent iterations of the patch series are labelled \"PATCH v2\", \"PATCH\n ++ v3\", etc. in place of \"PATCH\". For example, \"[PATCH v2 1/3]\" would be the first of\n ++ three patches in the second iteration. Each iteration is sent with a new cover\n ++ letter (like \"[PATCH v2 0/3]\" above), itself a reply to the cover letter of the\n ++ previous iteration (more on that below).\n ++\n ++NOTE: A single-patch topic is sent with \"[PATCH]\", \"[PATCH v2]\", etc. without\n ++_i_/_n_ numbering (in the above thread overview, no single-patch topic appears,\n ++though).\n ++\n +[[cover-letter]]\n +=== The cover letter\n +\n @@ Documentation/MyFirstContribution.txt: We can note a few things:\n +Be sure to explain anything your patches don't make clear on their own, but\n +remember that since the cover letter is not recorded in the commit history,\n +anything that might be useful to future readers of the repository's history\n -+should be in your commit messages, not in your cover letter.\n ++should also be in your commit messages.\n +\n +Here's an example body for `psuh`:\n +\n @@ Documentation/MyFirstContribution.txt: We can note a few things:\n +This patchset is part of the MyFirstContribution tutorial and should not\n +be merged.\n +----\n -+\n + \n At this point the tutorial diverges, in order to demonstrate two\n different methods of formatting your patchset and getting it reviewed.\n - \n @@ Documentation/MyFirstContribution.txt: but want reviewers to look at what they have so far. You can add this flag with\n Check and make sure that your patches and cover letter template exist in the\n directory you specified - you're nearly ready to send out your review!\n 3: d7699289ea6 = 3: 2caec6e619a MyFirstContribution: reference \"The cover letter\" in \"Preparing Email\"\n 4: f6034b0964b = 4: 02598d431e0 MyFirstContribution: reference \"The cover letter\" in GitGitGadget section\n 5: 33256c6b4ba = 5: 76bcb6612e4 MyFirstContribution: drop PR description for GGG single-patch contributions\n\n-- \ngitgitgadget\n"},{"id":"455240","messageId":"2caec6e619a89e9e10399da0feb04fa0a21b15a4.1652399017.git.gitgitgadget@gmail.com","threadId":"57807","inReplyTo":"pull.1226.v3.git.1652399017.gitgitgadget@gmail.com","subject":"[PATCH v3 3/5] MyFirstContribution: reference \"The cover letter\" in \"Preparing Email\"","fromName":"Philippe Blain via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-05-12T23:43:35Z","receivedAt":"2022-05-12T23:43:51Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"From: Philippe Blain \n\nThe previous commit added a standalone section on the purpose of the\ncover letter, drawing inspiration from the existing content of the\n\"Preparing Email\" section.\n\nAdjust \"Preparing Email\" to reference \"The cover letter\", to avoid\ncontent duplication.\n\nAlso, use the imperative mode for the cover letter subject, as is done\nin \"The cover letter\".\n\nSigned-off-by: Philippe Blain \n---\n Documentation/MyFirstContribution.txt | 38 +++++++--------------------\n 1 file changed, 9 insertions(+), 29 deletions(-)\n\ndiff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt\nindex 94f722d4b7f..f6ee5b8b1ae 100644\n--- a/Documentation/MyFirstContribution.txt\n+++ b/Documentation/MyFirstContribution.txt\n@@ -1046,46 +1046,26 @@ directory you specified - you're nearly ready to send out your review!\n [[preparing-cover-letter]]\n === Preparing Email\n \n-In addition to an email per patch, the Git community also expects your patches\n-to come with a cover letter, typically with a subject line [PATCH 0/x] (where\n-x is the number of patches you're sending). Since you invoked `format-patch`\n-with `--cover-letter`, you've already got a template ready. Open it up in your\n-favorite editor.\n+Since you invoked `format-patch` with `--cover-letter`, you've already got a\n+cover letter template ready. Open it up in your favorite editor.\n \n You should see a number of headers present already. Check that your `From:`\n-header is correct. Then modify your `Subject:` to something which succinctly\n-covers the purpose of your entire topic branch, for example:\n+header is correct. Then modify your `Subject:` (see <> for\n+how to choose good title for your patch series):\n \n ----\n-Subject: [PATCH 0/7] adding the 'psuh' command\n+Subject: [PATCH 0/7] Add the 'psuh' command\n ----\n \n Make sure you retain the ``[PATCH 0/X]'' part; that's what indicates to the Git\n-community that this email is the beginning of a review, and many reviewers\n-filter their email for this type of flag.\n+community that this email is the beginning of a patch series, and many\n+reviewers filter their email for this type of flag.\n \n You'll need to add some extra parameters when you invoke `git send-email` to add\n the cover letter.\n \n-Next you'll have to fill out the body of your cover letter. This is an important\n-component of change submission as it explains to the community from a high level\n-what you're trying to do, and why, in a way that's more apparent than just\n-looking at your diff. Be sure to explain anything your diff doesn't make clear\n-on its own.\n-\n-Here's an example body for `psuh`:\n-\n-----\n-Our internal metrics indicate widespread interest in the command\n-git-psuh - that is, many users are trying to use it, but finding it is\n-unavailable, using some unknown workaround instead.\n-\n-The following handful of patches add the psuh command and implement some\n-handy features on top of it.\n-\n-This patchset is part of the MyFirstContribution tutorial and should not\n-be merged.\n-----\n+Next you'll have to fill out the body of your cover letter. Again, see\n+<> for what content to include.\n \n The template created by `git format-patch --cover-letter` includes a diffstat.\n This gives reviewers a summary of what they're in for when reviewing your topic.\n-- \ngitgitgadget\n\n"},{"id":"455241","messageId":"59af7e5e5ad84103b39ac9511791eb06b88df3c6.1652399017.git.gitgitgadget@gmail.com","threadId":"57807","inReplyTo":"pull.1226.v3.git.1652399017.gitgitgadget@gmail.com","subject":"[PATCH v3 1/5] MyFirstContribution: add \"Anatomy of a Patch Series\" section","fromName":"Philippe Blain via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-05-12T23:43:33Z","receivedAt":"2022-05-12T23:43:55Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"From: Philippe Blain \n\nBefore describing how to send patches to the mailing list either with\nGitGitGadget or 'git send-email', the MyFirstContribution tutorial\nincludes a small \"Getting Ready to Share\" section where the two\ndifferent methods are briefly introduced.\n\nUse this section to also describe what a patch series looks like once\nsubmitted, so that readers get an understanding of the end result before\ndiving into how to accomplish that end result.\n\nStart by copying the \"thread overview\" section of a recent contribution\nfrom the public-inbox web UI and explaining how each commit is a\nseparate mail, and point out the cover letter.\n\nSubsequent commits will move the existing description of the purpose of\nthe cover letter from the 'git send-email' section to this \"anatomy\"\nsection.\n\nAlso, change the wording in the introductory paragraph to use\n\"contributions\" instead of \"patches\", since this makes more sense when\ntalking about GitHub pull requests.\n\nSigned-off-by: Philippe Blain \n---\n Documentation/MyFirstContribution.txt | 54 +++++++++++++++++++++++++--\n 1 file changed, 51 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt\nindex 63a2ef54493..22848f84bec 100644\n--- a/Documentation/MyFirstContribution.txt\n+++ b/Documentation/MyFirstContribution.txt\n@@ -710,13 +710,61 @@ dependencies. `prove` also makes the output nicer.\n Go ahead and commit this change, as well.\n \n [[ready-to-share]]\n-== Getting Ready to Share\n+== Getting Ready to Share: Anatomy of a Patch Series\n \n You may have noticed already that the Git project performs its code reviews via\n emailed patches, which are then applied by the maintainer when they are ready\n-and approved by the community. The Git project does not accept patches from\n+and approved by the community. The Git project does not accept contributions from\n pull requests, and the patches emailed for review need to be formatted a\n-specific way. At this point the tutorial diverges, in order to demonstrate two\n+specific way.\n+\n+:patch-series: https://lore.kernel.org/git/pull.1218.git.git.1645209647.gitgitgadget@gmail.com/\n+:lore: https://lore.kernel.org/git/\n+\n+Before taking a look at how to convert your commits into emailed patches,\n+let's analyze what the end result, a \"patch series\", looks like. Here is an\n+{patch-series}[example] of the summary view for a patch series on the web interface of\n+the {lore}[Git mailing list archive]:\n+\n+----\n+2022-02-18 18:40 [PATCH 0/3] libify reflog John Cai via GitGitGadget\n+2022-02-18 18:40 ` [PATCH 1/3] reflog: libify delete reflog function and helpers John Cai via GitGitGadget\n+2022-02-18 19:10 ` Ævar Arnfjörð Bjarmason [this message]\n+2022-02-18 19:39 ` Taylor Blau\n+2022-02-18 19:48 ` Ævar Arnfjörð Bjarmason\n+2022-02-18 19:35 ` Taylor Blau\n+2022-02-21 1:43 ` John Cai\n+2022-02-21 1:50 ` Taylor Blau\n+2022-02-23 19:50 ` John Cai\n+2022-02-18 20:00 ` // other replies ellided\n+2022-02-18 18:40 ` [PATCH 2/3] reflog: call reflog_delete from reflog.c John Cai via GitGitGadget\n+2022-02-18 19:15 ` Ævar Arnfjörð Bjarmason\n+2022-02-18 20:26 ` Junio C Hamano\n+2022-02-18 18:40 ` [PATCH 3/3] stash: call reflog_delete from reflog.c John Cai via GitGitGadget\n+2022-02-18 19:20 ` Ævar Arnfjörð Bjarmason\n+2022-02-19 0:21 ` Taylor Blau\n+2022-02-22 2:36 ` John Cai\n+2022-02-22 10:51 ` Ævar Arnfjörð Bjarmason\n+2022-02-18 19:29 ` [PATCH 0/3] libify reflog Ævar Arnfjörð Bjarmason\n+2022-02-22 18:30 ` [PATCH v2 0/3] libify reflog John Cai via GitGitGadget\n+2022-02-22 18:30 ` [PATCH v2 1/3] stash: add test to ensure reflog --rewrite --updatref behavior John Cai via GitGitGadget\n+2022-02-23 8:54 ` Ævar Arnfjörð Bjarmason\n+2022-02-23 21:27 ` Junio C Hamano\n+// continued\n+----\n+\n+We can note a few things:\n+\n+- Each commit is sent as a separate email, with the commit message title as\n+ subject, prefixed with \"[PATCH _i_/_n_]\" for the _i_-th commit of an\n+ _n_-commit series.\n+- Each patch is sent as a reply to an introductory email called the _cover\n+ letter_ of the series, prefixed \"[PATCH 0/_n_]\".\n+- Subsequent iterations of the patch series are labelled \"[PATCH v2]\", \"[PATCH\n+ v3]\", etc. and sent with a new cover letter, itself a reply to the cover\n+ letter of the previous iteration (more on that below).\n+\n+At this point the tutorial diverges, in order to demonstrate two\n different methods of formatting your patchset and getting it reviewed.\n \n The first method to be covered is GitGitGadget, which is useful for those\n-- \ngitgitgadget\n\n"},{"id":"455242","messageId":"76bcb6612e40aa3d5244658f9ff90f453222836a.1652399017.git.gitgitgadget@gmail.com","threadId":"57807","inReplyTo":"pull.1226.v3.git.1652399017.gitgitgadget@gmail.com","subject":"[PATCH v3 5/5] MyFirstContribution: drop PR description for GGG single-patch contributions","fromName":"Philippe Blain via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-05-12T23:43:37Z","receivedAt":"2022-05-12T23:43:56Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"From: Philippe Blain \n\nBy default, GitHub prefills the PR description using the commit message\nfor single-commit PRs. This results in a duplicate commit message below\nthe three-dash line if the contributor does not empty out the PR\ndescription before submitting, which adds noise for reviewers.\n\nAdd a note to that effect in MyFirstContribution.txt.\n\nThis partly addresses:\nhttps://github.com/gitgitgadget/gitgitgadget/issues/340\n\nSigned-off-by: Philippe Blain \n---\n Documentation/MyFirstContribution.txt | 10 ++++++++++\n 1 file changed, 10 insertions(+)\n\ndiff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt\nindex 9eb2dfec959..1da15d9ad44 100644\n--- a/Documentation/MyFirstContribution.txt\n+++ b/Documentation/MyFirstContribution.txt\n@@ -904,6 +904,16 @@ respectively as the subject and body of the cover letter for your change. Refer\n to <> above for advice on how to title your\n submission and what content to include in the description.\n \n+NOTE: For single-patch contributions, your commit message should already be\n+meaningful and explain at a high level the purpose (what is happening and why)\n+of your patch, so you usually do not need any additional context. In that case,\n+remove the PR description that GitHub automatically generates from your commit\n+message (your PR description should be empty). If you do need to supply even\n+more context, you can do so in that space and it will be appended to the email\n+that GitGitGadget will send, between the three-dash line and the diffstat\n+(see <> for how this looks once\n+submitted).\n+\n When you're happy, submit your pull request.\n \n [[run-ci-ggg]]\n-- \ngitgitgadget\n"},{"id":"455243","messageId":"02598d431e0eb4f7cad9b7703c2fb244c3d15781.1652399017.git.gitgitgadget@gmail.com","threadId":"57807","inReplyTo":"pull.1226.v3.git.1652399017.gitgitgadget@gmail.com","subject":"[PATCH v3 4/5] MyFirstContribution: reference \"The cover letter\" in GitGitGadget section","fromName":"Philippe Blain via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-05-12T23:43:36Z","receivedAt":"2022-05-12T23:43:59Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"From: Philippe Blain \n\nThe \"Sending Patches via GitGitGadget\" section mentions that the PR\ntitle and description will be used as the cover letter, but does not\nexplain what is a cover letter or what should be included in it.\n\nRefer readers to the new \"The cover letter\" section added in a previous\ncommit.\n\nSigned-off-by: Philippe Blain \n---\n Documentation/MyFirstContribution.txt | 8 ++++++--\n 1 file changed, 6 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt\nindex f6ee5b8b1ae..9eb2dfec959 100644\n--- a/Documentation/MyFirstContribution.txt\n+++ b/Documentation/MyFirstContribution.txt\n@@ -899,8 +899,12 @@ https://github.com/gitgitgadget/git and open a PR either with the \"New pull\n request\" button or the convenient \"Compare & pull request\" button that may\n appear with the name of your newly pushed branch.\n \n-Review the PR's title and description, as it's used by GitGitGadget as the cover\n-letter for your change. When you're happy, submit your pull request.\n+Review the PR's title and description, as they're used by GitGitGadget\n+respectively as the subject and body of the cover letter for your change. Refer\n+to <> above for advice on how to title your\n+submission and what content to include in the description.\n+\n+When you're happy, submit your pull request.\n \n [[run-ci-ggg]]\n === Running CI and Getting Ready to Send\n-- \ngitgitgadget\n\n"},{"id":"455244","messageId":"ee3238f5a9169f0c7d046089c7951791b8db3cab.1652399017.git.gitgitgadget@gmail.com","threadId":"57807","inReplyTo":"pull.1226.v3.git.1652399017.gitgitgadget@gmail.com","subject":"[PATCH v3 2/5] MyFirstContribution: add standalone section on cover letter","fromName":"Philippe Blain via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-05-12T23:43:34Z","receivedAt":"2022-05-12T23:44:01Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"From: Philippe Blain \n\nAn explanation of the purpose of the cover letter is included in the\n\"Sending Patches with git send-email\" / \"Preparing Email\" section but is\nmissing from the \"Sending Patches via GitGitGadget\" section.\n\nAdd a standalone section \"The cover letter\" under the \"Getting Started:\nAnatomy of a Patch Series\" header to explain what the cover letter is\nused for and to draft the cover letter of the 'psuh' topic used in the\ntutorial.\n\nFor now we mostly copy content from the \"Sending Patches with git\nsend-email\" section but do not adjust that section, nor the GGG section,\nto reference the new section. This is done in following commits.\n\nAlso, adjust the \"Preparing Email\" Asciidoc anchor to avoid conflicts.\n\nSigned-off-by: Philippe Blain \n---\n Documentation/MyFirstContribution.txt | 51 ++++++++++++++++++++++++---\n 1 file changed, 47 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt\nindex 22848f84bec..94f722d4b7f 100644\n--- a/Documentation/MyFirstContribution.txt\n+++ b/Documentation/MyFirstContribution.txt\n@@ -760,9 +760,52 @@ We can note a few things:\n _n_-commit series.\n - Each patch is sent as a reply to an introductory email called the _cover\n letter_ of the series, prefixed \"[PATCH 0/_n_]\".\n-- Subsequent iterations of the patch series are labelled \"[PATCH v2]\", \"[PATCH\n- v3]\", etc. and sent with a new cover letter, itself a reply to the cover\n- letter of the previous iteration (more on that below).\n+- Subsequent iterations of the patch series are labelled \"PATCH v2\", \"PATCH\n+ v3\", etc. in place of \"PATCH\". For example, \"[PATCH v2 1/3]\" would be the first of\n+ three patches in the second iteration. Each iteration is sent with a new cover\n+ letter (like \"[PATCH v2 0/3]\" above), itself a reply to the cover letter of the\n+ previous iteration (more on that below).\n+\n+NOTE: A single-patch topic is sent with \"[PATCH]\", \"[PATCH v2]\", etc. without\n+_i_/_n_ numbering (in the above thread overview, no single-patch topic appears,\n+though).\n+\n+[[cover-letter]]\n+=== The cover letter\n+\n+In addition to an email per patch, the Git community also expects your patches\n+to come with a cover letter. This is an important component of change\n+submission as it explains to the community from a high level what you're trying\n+to do, and why, in a way that's more apparent than just looking at your\n+patches.\n+\n+The title of your cover letter should be something which succinctly covers the\n+purpose of your entire topic branch. It's often in the imperative mood, just\n+like our commit message titles. Here is how we'll title our series:\n+\n+---\n+Add the 'psuh' command\n+---\n+\n+The body of the cover letter is used to give additional context to reviewers.\n+Be sure to explain anything your patches don't make clear on their own, but\n+remember that since the cover letter is not recorded in the commit history,\n+anything that might be useful to future readers of the repository's history\n+should also be in your commit messages.\n+\n+Here's an example body for `psuh`:\n+\n+----\n+Our internal metrics indicate widespread interest in the command\n+git-psuh - that is, many users are trying to use it, but finding it is\n+unavailable, using some unknown workaround instead.\n+\n+The following handful of patches add the psuh command and implement some\n+handy features on top of it.\n+\n+This patchset is part of the MyFirstContribution tutorial and should not\n+be merged.\n+----\n \n At this point the tutorial diverges, in order to demonstrate two\n different methods of formatting your patchset and getting it reviewed.\n@@ -1000,7 +1043,7 @@ but want reviewers to look at what they have so far. You can add this flag with\n Check and make sure that your patches and cover letter template exist in the\n directory you specified - you're nearly ready to send out your review!\n \n-[[cover-letter]]\n+[[preparing-cover-letter]]\n === Preparing Email\n \n In addition to an email per patch, the Git community also expects your patches\n-- \ngitgitgadget\n\n"},{"id":"455541","messageId":"xmqqpmk9kxa8.fsf@gitster.g","threadId":"57807","inReplyTo":"pull.1226.v3.git.1652399017.gitgitgadget@gmail.com","subject":"Re: [PATCH v3 0/5] Improve MyFirstContribution's GitGitGadget section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-05-19T21:49:51Z","receivedAt":"2022-05-19T21:49:56Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philippe Blain via GitGitGadget\" writes:\n\n> Philippe Blain (5):\n> MyFirstContribution: add \"Anatomy of a Patch Series\" section\n> MyFirstContribution: add standalone section on cover letter\n> MyFirstContribution: reference \"The cover letter\" in \"Preparing Email\"\n> MyFirstContribution: reference \"The cover letter\" in GitGitGadget\n> section\n> MyFirstContribution: drop PR description for GGG single-patch\n> contributions\n\nI am planning to merge it to 'next' soonish. Please speak up if\nanybody has any issues.\n\nThanks.\n"},{"id":"455698","messageId":"f47761e0-bbaa-e4a5-b74e-e9c211bd8d85@gmail.com","threadId":"57807","inReplyTo":"xmqqpmk9kxa8.fsf@gitster.g","subject":"Re: [PATCH v3 0/5] Improve MyFirstContribution's GitGitGadget section","fromName":"Philippe Blain","fromEmail":"levraiphilippeblain@gmail.com","sentAt":"2022-05-21T16:17:12Z","receivedAt":"2022-05-21T16:17:19Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"Hi Junio,\n\nLe 2022-05-19 à 17:49, Junio C Hamano a écrit :\n> \"Philippe Blain via GitGitGadget\" writes:\n> \n>> Philippe Blain (5):\n>> MyFirstContribution: add \"Anatomy of a Patch Series\" section\n>> MyFirstContribution: add standalone section on cover letter\n>> MyFirstContribution: reference \"The cover letter\" in \"Preparing Email\"\n>> MyFirstContribution: reference \"The cover letter\" in GitGitGadget\n>> section\n>> MyFirstContribution: drop PR description for GGG single-patch\n>> contributions\n> \n> I am planning to merge it to 'next' soonish. Please speak up if\n> anybody has any issues.\n> \n> Thanks.\n> \n\nI just realized that the additional/tweaked content that I added in v3 went into 2/5\nwhere as they should have gone into 1/5 (I'm talking about the changes \n*before* the \"The cover letter\" heading in [1]). I slightly messed up my rebase\nit seems, I'm sorry... \n\nShould I send a new version, or is it too late since it's now in 'next' ?\n\nThanks,\n\nPhilippe.\n\n[1] https://github.com/gitgitgadget/git/pull/1226/commits/ee3238f5a9169f0c7d046089c7951791b8db3cab\n"},{"id":"455726","messageId":"xmqqy1yubb8j.fsf@gitster.g","threadId":"57807","inReplyTo":"f47761e0-bbaa-e4a5-b74e-e9c211bd8d85@gmail.com","subject":"Re: [PATCH v3 0/5] Improve MyFirstContribution's GitGitGadget section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-05-22T01:35:24Z","receivedAt":"2022-05-22T01:35:33Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philippe Blain writes:\n\n>>> Philippe Blain (5):\n>>> MyFirstContribution: add \"Anatomy of a Patch Series\" section\n>>> MyFirstContribution: add standalone section on cover letter\n>>> MyFirstContribution: reference \"The cover letter\" in \"Preparing Email\"\n>>> MyFirstContribution: reference \"The cover letter\" in GitGitGadget\n>>> section\n>>> MyFirstContribution: drop PR description for GGG single-patch\n>>> contributions\n> I just realized that the additional/tweaked content that I added in v3 went into 2/5\n> where as they should have gone into 1/5 (I'm talking about the changes \n> *before* the \"The cover letter\" heading in [1]). I slightly messed up my rebase\n> it seems, I'm sorry... \n>\n> Should I send a new version, or is it too late since it's now in 'next' ?\n\nThanks for letting me know, and sorry about the confusion.\n\nCould you please send an incremental fix to be queued on top of\nthese 5 patches?\n\nThanks.\n"},{"id":"455894","messageId":"0a2ab37e-58c0-378e-bc43-a935c8ebecec@gmail.com","threadId":"57807","inReplyTo":"xmqqy1yubb8j.fsf@gitster.g","subject":"Re: [PATCH v3 0/5] Improve MyFirstContribution's GitGitGadget section","fromName":"Philippe Blain","fromEmail":"levraiphilippeblain@gmail.com","sentAt":"2022-05-24T12:29:51Z","receivedAt":"2022-05-24T12:30:00Z","isPatch":true,"sender":{"key":"levraiphilippeblain@gmail.com","avatar":"https://avatars.githubusercontent.com/u/44212482?v=4"},"body":"Hi Junio,\n\nLe 2022-05-21 à 21:35, Junio C Hamano a écrit :\n> Philippe Blain writes:\n> \n>>>> Philippe Blain (5):\n>>>> MyFirstContribution: add \"Anatomy of a Patch Series\" section\n>>>> MyFirstContribution: add standalone section on cover letter\n>>>> MyFirstContribution: reference \"The cover letter\" in \"Preparing Email\"\n>>>> MyFirstContribution: reference \"The cover letter\" in GitGitGadget\n>>>> section\n>>>> MyFirstContribution: drop PR description for GGG single-patch\n>>>> contributions\n>> I just realized that the additional/tweaked content that I added in v3 went into 2/5\n>> where as they should have gone into 1/5 (I'm talking about the changes \n>> *before* the \"The cover letter\" heading in [1]). I slightly messed up my rebase\n>> it seems, I'm sorry... \n>>\n>> Should I send a new version, or is it too late since it's now in 'next' ?\n> \n> Thanks for letting me know, and sorry about the confusion.\n> \n> Could you please send an incremental fix to be queued on top of\n> these 5 patches?\n\nI can't really send an incremental fix because the final content\nas it is in 'next' already is OK; it's just that some content which was added\nin patch 2/5 should have been added in 1/5 instead.\n\nIt's that too big of a deal, I just wanted to let you know.\n\nThanks,\nPhilippe.\n"},{"id":"455928","messageId":"xmqq5yluiwcp.fsf@gitster.g","threadId":"57807","inReplyTo":"0a2ab37e-58c0-378e-bc43-a935c8ebecec@gmail.com","subject":"Re: [PATCH v3 0/5] Improve MyFirstContribution's GitGitGadget section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-05-24T19:06:30Z","receivedAt":"2022-05-24T19:06:45Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philippe Blain writes:\n\n> I can't really send an incremental fix because the final content\n> as it is in 'next' already is OK; it's just that some content which was added\n> in patch 2/5 should have been added in 1/5 instead.\n>\n> It's that too big of a deal, I just wanted to let you know.\n\nAh, I mis-read you then.\n\nSuch a misdivision may technically break bisectability, but\nhopefully nobody bisects the documentation changes and I do not\nthink we should be worried too much about it.\n\nThanks.\n"}]}