* [PATCH v2 1/5] MyFirstContribution: add "Anatomy of a Patch Series" section
2022-05-11 1:47 ` [PATCH v2 0/5] Improve MyFirstContribution's GitGitGadget section Philippe Blain via GitGitGadget
@ 2022-05-11 1:47 ` Philippe Blain via GitGitGadget
2022-05-11 6:20 ` Bagas Sanjaya
2022-05-12 12:11 ` Philip Oakley
2022-05-11 1:47 ` [PATCH v2 2/5] MyFirstContribution: add standalone section on cover letter Philippe Blain via GitGitGadget
` (6 subsequent siblings)
7 siblings, 2 replies; 43+ messages in thread
From: Philippe Blain via GitGitGadget @ 2022-05-11 1:47 UTC (permalink / raw)
To: git
Cc: Emily Shaffer, Johannes Schindelin, Victoria Dye, Eric Sunshine,
Philippe Blain, Philippe Blain, Philippe Blain
From: Philippe Blain <levraiphilippeblain@gmail.com>
Before describing how to send patches to the mailing list either with
GitGitGadget or 'git send-email', the MyFirstContribution tutorial
includes a small "Getting Ready to Share" section where the two
different methods are briefly introduced.
Use this section to also describe what a patch series looks like once
submitted, so that readers get an understanding of the end result before
diving into how to accomplish that end result.
Start by copying the "thread overview" section of a recent contribution
from the public-inbox web UI and explaining how each commit is a
separate mail, and point out the cover letter.
Subsequent commits will move the existing description of the purpose of
the cover letter from the 'git send-email' section to this "anatomy"
section.
Also, change the wording in the introductory paragraph to use
"contributions" instead of "patches", since this makes more sense when
talking about GitHub pull requests.
Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
Documentation/MyFirstContribution.txt | 54 +++++++++++++++++++++++++--
1 file changed, 51 insertions(+), 3 deletions(-)
diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index 63a2ef54493..22848f84bec 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -710,13 +710,61 @@ dependencies. `prove` also makes the output nicer.
Go ahead and commit this change, as well.
[[ready-to-share]]
-== Getting Ready to Share
+== Getting Ready to Share: Anatomy of a Patch Series
You may have noticed already that the Git project performs its code reviews via
emailed patches, which are then applied by the maintainer when they are ready
-and approved by the community. The Git project does not accept patches from
+and approved by the community. The Git project does not accept contributions from
pull requests, and the patches emailed for review need to be formatted a
-specific way. At this point the tutorial diverges, in order to demonstrate two
+specific way.
+
+:patch-series: https://lore.kernel.org/git/pull.1218.git.git.1645209647.gitgitgadget@gmail.com/
+:lore: https://lore.kernel.org/git/
+
+Before taking a look at how to convert your commits into emailed patches,
+let's analyze what the end result, a "patch series", looks like. Here is an
+{patch-series}[example] of the summary view for a patch series on the web interface of
+the {lore}[Git mailing list archive]:
+
+----
+2022-02-18 18:40 [PATCH 0/3] libify reflog John Cai via GitGitGadget
+2022-02-18 18:40 ` [PATCH 1/3] reflog: libify delete reflog function and helpers John Cai via GitGitGadget
+2022-02-18 19:10 ` Ævar Arnfjörð Bjarmason [this message]
+2022-02-18 19:39 ` Taylor Blau
+2022-02-18 19:48 ` Ævar Arnfjörð Bjarmason
+2022-02-18 19:35 ` Taylor Blau
+2022-02-21 1:43 ` John Cai
+2022-02-21 1:50 ` Taylor Blau
+2022-02-23 19:50 ` John Cai
+2022-02-18 20:00 ` // other replies ellided
+2022-02-18 18:40 ` [PATCH 2/3] reflog: call reflog_delete from reflog.c John Cai via GitGitGadget
+2022-02-18 19:15 ` Ævar Arnfjörð Bjarmason
+2022-02-18 20:26 ` Junio C Hamano
+2022-02-18 18:40 ` [PATCH 3/3] stash: call reflog_delete from reflog.c John Cai via GitGitGadget
+2022-02-18 19:20 ` Ævar Arnfjörð Bjarmason
+2022-02-19 0:21 ` Taylor Blau
+2022-02-22 2:36 ` John Cai
+2022-02-22 10:51 ` Ævar Arnfjörð Bjarmason
+2022-02-18 19:29 ` [PATCH 0/3] libify reflog Ævar Arnfjörð Bjarmason
+2022-02-22 18:30 ` [PATCH v2 0/3] libify reflog John Cai via GitGitGadget
+2022-02-22 18:30 ` [PATCH v2 1/3] stash: add test to ensure reflog --rewrite --updatref behavior John Cai via GitGitGadget
+2022-02-23 8:54 ` Ævar Arnfjörð Bjarmason
+2022-02-23 21:27 ` Junio C Hamano
+// continued
+----
+
+We can note a few things:
+
+- Each commit is sent as a separate email, with the commit message title as
+ subject, prefixed with "[PATCH _i_/_n_]" for the _i_-th commit of an
+ _n_-commit series.
+- Each patch is sent as a reply to an introductory email called the _cover
+ letter_ of the series, prefixed "[PATCH 0/_n_]".
+- Subsequent iterations of the patch series are labelled "[PATCH v2]", "[PATCH
+ v3]", etc. and sent with a new cover letter, itself a reply to the cover
+ letter of the previous iteration (more on that below).
+
+At this point the tutorial diverges, in order to demonstrate two
different methods of formatting your patchset and getting it reviewed.
The first method to be covered is GitGitGadget, which is useful for those
--
gitgitgadget
^ permalink raw reply related [flat|nested] 43+ messages in thread
* Re: [PATCH v2 1/5] MyFirstContribution: add "Anatomy of a Patch Series" section
2022-05-11 1:47 ` [PATCH v2 1/5] MyFirstContribution: add "Anatomy of a Patch Series" section Philippe Blain via GitGitGadget
@ 2022-05-11 6:20 ` Bagas Sanjaya
2022-05-11 21:30 ` Junio C Hamano
2022-05-12 12:11 ` Philip Oakley
1 sibling, 1 reply; 43+ messages in thread
From: Bagas Sanjaya @ 2022-05-11 6:20 UTC (permalink / raw)
To: Philippe Blain via GitGitGadget
Cc: git, Emily Shaffer, Johannes Schindelin, Victoria Dye,
Eric Sunshine, Philippe Blain
On Wed, May 11, 2022 at 01:47:30AM +0000, Philippe Blain via GitGitGadget wrote:
> +We can note a few things:
> +
> +- Each commit is sent as a separate email, with the commit message title as
> + subject, prefixed with "[PATCH _i_/_n_]" for the _i_-th commit of an
> + _n_-commit series.
> +- Each patch is sent as a reply to an introductory email called the _cover
> + letter_ of the series, prefixed "[PATCH 0/_n_]".
> +- Subsequent iterations of the patch series are labelled "[PATCH v2]", "[PATCH
> + v3]", etc. and sent with a new cover letter, itself a reply to the cover
> + letter of the previous iteration (more on that below).
> +
> +At this point the tutorial diverges, in order to demonstrate two
> different methods of formatting your patchset and getting it reviewed.
>
In case of single-patch series submissions, the anatomy is simple: first
the email subject is commit message title prefixed with "[PATCH]" or
"[PATCH v_n_]" (in case of n-th iteration), then commit message and the
actual diff.
Regarding n-th iteration series, sometimes it is desirable to break the
threading so that the original thread (of previous iterations) doesn't
get too long, by sending the series as completely new thread. Some
contributors (including myself) prefer that way. In that case, the link
to previous iteration is provided to aid reviewers.
--
An old man doll... just what I always wanted! - Clara
^ permalink raw reply [flat|nested] 43+ messages in thread
* Re: [PATCH v2 1/5] MyFirstContribution: add "Anatomy of a Patch Series" section
2022-05-11 6:20 ` Bagas Sanjaya
@ 2022-05-11 21:30 ` Junio C Hamano
2022-05-11 21:48 ` Philippe Blain
0 siblings, 1 reply; 43+ messages in thread
From: Junio C Hamano @ 2022-05-11 21:30 UTC (permalink / raw)
To: Bagas Sanjaya
Cc: Philippe Blain via GitGitGadget, git, Emily Shaffer,
Johannes Schindelin, Victoria Dye, Eric Sunshine, Philippe Blain
Bagas Sanjaya <bagasdotme@gmail.com> writes:
> On Wed, May 11, 2022 at 01:47:30AM +0000, Philippe Blain via GitGitGadget wrote:
>> +We can note a few things:
>> +
>> +- Each commit is sent as a separate email, with the commit message title as
>> + subject, prefixed with "[PATCH _i_/_n_]" for the _i_-th commit of an
>> + _n_-commit series.
>> +- Each patch is sent as a reply to an introductory email called the _cover
>> + letter_ of the series, prefixed "[PATCH 0/_n_]".
>> +- Subsequent iterations of the patch series are labelled "[PATCH v2]", "[PATCH
>> + v3]", etc. and sent with a new cover letter, itself a reply to the cover
>> + letter of the previous iteration (more on that below).
>> +
>> +At this point the tutorial diverges, in order to demonstrate two
>> different methods of formatting your patchset and getting it reviewed.
>>
>
> In case of single-patch series submissions, the anatomy is simple: first
> the email subject is commit message title prefixed with "[PATCH]" or
> "[PATCH v_n_]" (in case of n-th iteration), then commit message and the
> actual diff.
Correct. There is no single-patch topic in the summary view shown
in the document, so it does not belong to the above "We can note a
few things" list. But I agree that there should be a mention for a
single-patch topic somewhere in this document, both for a patch and
(the usual lack of) cover-letter for such a topic.
The sample topic this tutorial uses is a multi-patch series and
everything in the document revolves around handing a multi-patch
series, so finding a good place to fit it may be a bit tricky,
though.
> Regarding n-th iteration series, sometimes it is desirable to break the
> threading so that the original thread (of previous iterations) doesn't
> get too long, by sending the series as completely new thread. Some
> contributors (including myself) prefer that way. In that case, the link
> to previous iteration is provided to aid reviewers.
This is often not very friendly to reviewers, unless the "new topic"
is so different that it is almost totally unrelated to the old one.
Even in a "in earlier round, we perceived X as a problem and tried
to solve it, but it turns out it is better to solve Y instead" case,
it often helps to learn the reason why we ended up not addressing X
after you use "git blame" to find a commit that solved Y in a later
iteration and wonder why an approach to solve X was not taken. It
is a very good idea to mention the need to add a link to a previous
thread if the submitter decides to break the thread.
Thanks.
^ permalink raw reply [flat|nested] 43+ messages in thread
* Re: [PATCH v2 1/5] MyFirstContribution: add "Anatomy of a Patch Series" section
2022-05-11 21:30 ` Junio C Hamano
@ 2022-05-11 21:48 ` Philippe Blain
2022-05-11 22:09 ` Junio C Hamano
0 siblings, 1 reply; 43+ messages in thread
From: Philippe Blain @ 2022-05-11 21:48 UTC (permalink / raw)
To: Junio C Hamano, Bagas Sanjaya
Cc: Philippe Blain via GitGitGadget, git, Emily Shaffer,
Johannes Schindelin, Victoria Dye, Eric Sunshine
Hi Bagas and Junio,
Le 2022-05-11 à 17:30, Junio C Hamano a écrit :
> Bagas Sanjaya <bagasdotme@gmail.com> writes:
>
>> On Wed, May 11, 2022 at 01:47:30AM +0000, Philippe Blain via GitGitGadget wrote:
>>> +We can note a few things:
>>> +
>>> +- Each commit is sent as a separate email, with the commit message title as
>>> + subject, prefixed with "[PATCH _i_/_n_]" for the _i_-th commit of an
>>> + _n_-commit series.
>>> +- Each patch is sent as a reply to an introductory email called the _cover
>>> + letter_ of the series, prefixed "[PATCH 0/_n_]".
>>> +- Subsequent iterations of the patch series are labelled "[PATCH v2]", "[PATCH
>>> + v3]", etc. and sent with a new cover letter, itself a reply to the cover
>>> + letter of the previous iteration (more on that below).
>>> +
>>> +At this point the tutorial diverges, in order to demonstrate two
>>> different methods of formatting your patchset and getting it reviewed.
>>>
>>
>> In case of single-patch series submissions, the anatomy is simple: first
>> the email subject is commit message title prefixed with "[PATCH]" or
>> "[PATCH v_n_]" (in case of n-th iteration), then commit message and the
>> actual diff.
>
> Correct. There is no single-patch topic in the summary view shown
> in the document, so it does not belong to the above "We can note a
> few things" list. But I agree that there should be a mention for a
> single-patch topic somewhere in this document, both for a patch and
> (the usual lack of) cover-letter for such a topic.
>
> The sample topic this tutorial uses is a multi-patch series and
> everything in the document revolves around handing a multi-patch
> series, so finding a good place to fit it may be a bit tricky,
> though.
There is already a small section on single-patch topics, at the end of
the 'git send-email' section [1]. And I add a link to it in the GGG
section in patch 5/5.
[1] https://git-scm.com/docs/MyFirstContribution#single-patch
>> Regarding n-th iteration series, sometimes it is desirable to break the
>> threading so that the original thread (of previous iterations) doesn't
>> get too long, by sending the series as completely new thread. Some
>> contributors (including myself) prefer that way. In that case, the link
>> to previous iteration is provided to aid reviewers.
>
> This is often not very friendly to reviewers, unless the "new topic"
> is so different that it is almost totally unrelated to the old one.
>
> Even in a "in earlier round, we perceived X as a problem and tried
> to solve it, but it turns out it is better to solve Y instead" case,
> it often helps to learn the reason why we ended up not addressing X
> after you use "git blame" to find a commit that solved Y in a later
> iteration and wonder why an approach to solve X was not taken. It
> is a very good idea to mention the need to add a link to a previous
> thread if the submitter decides to break the thread.
Thanks for confirming. I think for a beginner tutorial like MyFirstContribution,
we should keep things simple, so I would leave the content as-is regarding threading.
If we ever revive the "mailing list etiquette" series, then I think we could add
notes regarding this kind of things.
Cheers,
Philippe.
^ permalink raw reply [flat|nested] 43+ messages in thread
* Re: [PATCH v2 1/5] MyFirstContribution: add "Anatomy of a Patch Series" section
2022-05-11 21:48 ` Philippe Blain
@ 2022-05-11 22:09 ` Junio C Hamano
2022-05-12 23:00 ` Philippe Blain
0 siblings, 1 reply; 43+ messages in thread
From: Junio C Hamano @ 2022-05-11 22:09 UTC (permalink / raw)
To: Philippe Blain
Cc: Bagas Sanjaya, Philippe Blain via GitGitGadget, git,
Emily Shaffer, Johannes Schindelin, Victoria Dye, Eric Sunshine
Philippe Blain <levraiphilippeblain@gmail.com> writes:
>> Bagas Sanjaya <bagasdotme@gmail.com> writes:
>>
>>> On Wed, May 11, 2022 at 01:47:30AM +0000, Philippe Blain via GitGitGadget wrote:
>>>> +We can note a few things:
>>>> +
>>>> +- Each commit is sent as a separate email, with the commit message title as
>>>> + subject, prefixed with "[PATCH _i_/_n_]" for the _i_-th commit of an
>>>> + _n_-commit series.
>>>> +- Each patch is sent as a reply to an introductory email called the _cover
>>>> + letter_ of the series, prefixed "[PATCH 0/_n_]".
>>>> +- Subsequent iterations of the patch series are labelled "[PATCH v2]", "[PATCH
>>>> + v3]", etc. and sent with a new cover letter, itself a reply to the cover
>>>> + letter of the previous iteration (more on that below).
>>>> +
>>>> +At this point the tutorial diverges, in order to demonstrate two
>>>> different methods of formatting your patchset and getting it reviewed.
>>>>
>>>
>>> In case of single-patch series submissions, the anatomy is simple: first
>>> the email subject is commit message title prefixed with "[PATCH]" or
>>> "[PATCH v_n_]" (in case of n-th iteration), then commit message and the
>>> actual diff.
>>
>> Correct. There is no single-patch topic in the summary view shown
>> in the document, so it does not belong to the above "We can note a
>> few things" list. But I agree that there should be a mention for a
>> single-patch topic somewhere in this document, both for a patch and
>> (the usual lack of) cover-letter for such a topic.
>>
>> The sample topic this tutorial uses is a multi-patch series and
>> everything in the document revolves around handing a multi-patch
>> series, so finding a good place to fit it may be a bit tricky,
>> though.
>
> There is already a small section on single-patch topics, at the end of
> the 'git send-email' section [1]. And I add a link to it in the GGG
> section in patch 5/5.
>
> [1] https://git-scm.com/docs/MyFirstContribution#single-patch
Yup, I was wondering if there is an easy way to move it to this
section, which imparts a knowledge common across different method of
patch submission. If we can do so somewhere nearby, it would be
ideal. Perhaps in "We can note a few things" list or as a side note
immediately after the list, we can add
- A single-patch topic is sent with "[PATCH]", "[PATCH v2]",
etc. without _i_/_n_ numbering (in the above thread overview,
no single-patch topic appears, though).
Or we can redo the lore screenshot to include such a topic, perhaps,
then we can lose the comment in the parentheses.
That reminds me of one small bug in your patch, where it says
>>>> +- Subsequent iterations of the patch series are labelled "[PATCH v2]", "[PATCH
>>>> + v3]", etc. and sent with a new cover letter, itself a reply to the cover
>>>> + letter of the previous iteration (more on that below).
Subsequent interations of the patches and the cover letter use
"PATCH v2", "PATCH v3", etc. in place of "PATCH". "[PATCH v2
1/3]" would be the first of three patches in the second
iteration, for example, and replies to "[PATCH v2 0/3]" which is
the cover letter for the iteration, which in turn replies to the
cover letter of the first iteration.
Thanks.
^ permalink raw reply [flat|nested] 43+ messages in thread
* Re: [PATCH v2 1/5] MyFirstContribution: add "Anatomy of a Patch Series" section
2022-05-11 22:09 ` Junio C Hamano
@ 2022-05-12 23:00 ` Philippe Blain
0 siblings, 0 replies; 43+ messages in thread
From: Philippe Blain @ 2022-05-12 23:00 UTC (permalink / raw)
To: Junio C Hamano
Cc: Bagas Sanjaya, Philippe Blain via GitGitGadget, git,
Emily Shaffer, Johannes Schindelin, Victoria Dye, Eric Sunshine
Hi Junio,
Le 2022-05-11 à 18:09, Junio C Hamano a écrit :
> Philippe Blain <levraiphilippeblain@gmail.com> writes:
>
>>> Bagas Sanjaya <bagasdotme@gmail.com> writes:
>>>
>>>> On Wed, May 11, 2022 at 01:47:30AM +0000, Philippe Blain via GitGitGadget wrote:
>>>>> +We can note a few things:
>>>>> +
>>>>> +- Each commit is sent as a separate email, with the commit message title as
>>>>> + subject, prefixed with "[PATCH _i_/_n_]" for the _i_-th commit of an
>>>>> + _n_-commit series.
>>>>> +- Each patch is sent as a reply to an introductory email called the _cover
>>>>> + letter_ of the series, prefixed "[PATCH 0/_n_]".
>>>>> +- Subsequent iterations of the patch series are labelled "[PATCH v2]", "[PATCH
>>>>> + v3]", etc. and sent with a new cover letter, itself a reply to the cover
>>>>> + letter of the previous iteration (more on that below).
>>>>> +
>>>>> +At this point the tutorial diverges, in order to demonstrate two
>>>>> different methods of formatting your patchset and getting it reviewed.
>>>>>
>>>>
>>>> In case of single-patch series submissions, the anatomy is simple: first
>>>> the email subject is commit message title prefixed with "[PATCH]" or
>>>> "[PATCH v_n_]" (in case of n-th iteration), then commit message and the
>>>> actual diff.
>>>
>>> Correct. There is no single-patch topic in the summary view shown
>>> in the document, so it does not belong to the above "We can note a
>>> few things" list. But I agree that there should be a mention for a
>>> single-patch topic somewhere in this document, both for a patch and
>>> (the usual lack of) cover-letter for such a topic.
>>>
>>> The sample topic this tutorial uses is a multi-patch series and
>>> everything in the document revolves around handing a multi-patch
>>> series, so finding a good place to fit it may be a bit tricky,
>>> though.
>>
>> There is already a small section on single-patch topics, at the end of
>> the 'git send-email' section [1]. And I add a link to it in the GGG
>> section in patch 5/5.
>>
>> [1] https://git-scm.com/docs/MyFirstContribution#single-patch
>
> Yup, I was wondering if there is an easy way to move it to this
> section, which imparts a knowledge common across different method of
> patch submission. If we can do so somewhere nearby, it would be
> ideal. Perhaps in "We can note a few things" list or as a side note
> immediately after the list, we can add
>
> - A single-patch topic is sent with "[PATCH]", "[PATCH v2]",
> etc. without _i_/_n_ numbering (in the above thread overview,
> no single-patch topic appears, though).
>
> Or we can redo the lore screenshot to include such a topic, perhaps,
> then we can lose the comment in the parentheses.
OK, a little side note sounds good.
> That reminds me of one small bug in your patch, where it says
>
>>>>> +- Subsequent iterations of the patch series are labelled "[PATCH v2]", "[PATCH
>>>>> + v3]", etc. and sent with a new cover letter, itself a reply to the cover
>>>>> + letter of the previous iteration (more on that below).
>
> Subsequent interations of the patches and the cover letter use
> "PATCH v2", "PATCH v3", etc. in place of "PATCH". "[PATCH v2
> 1/3]" would be the first of three patches in the second
> iteration, for example, and replies to "[PATCH v2 0/3]" which is
> the cover letter for the iteration, which in turn replies to the
> cover letter of the first iteration.
OK, I will add more details along these lines.
^ permalink raw reply [flat|nested] 43+ messages in thread
* Re: [PATCH v2 1/5] MyFirstContribution: add "Anatomy of a Patch Series" section
2022-05-11 1:47 ` [PATCH v2 1/5] MyFirstContribution: add "Anatomy of a Patch Series" section Philippe Blain via GitGitGadget
2022-05-11 6:20 ` Bagas Sanjaya
@ 2022-05-12 12:11 ` Philip Oakley
2022-05-12 22:53 ` Philippe Blain
1 sibling, 1 reply; 43+ messages in thread
From: Philip Oakley @ 2022-05-12 12:11 UTC (permalink / raw)
To: Philippe Blain via GitGitGadget, git
Cc: Emily Shaffer, Johannes Schindelin, Victoria Dye, Eric Sunshine,
Philippe Blain
On 11/05/2022 02:47, Philippe Blain via GitGitGadget wrote:
> diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
> index 63a2ef54493..22848f84bec 100644
> --- a/Documentation/MyFirstContribution.txt
> +++ b/Documentation/MyFirstContribution.txt
> @@ -710,13 +710,61 @@ dependencies. `prove` also makes the output nicer.
> Go ahead and commit this change, as well.
>
> [[ready-to-share]]
> -== Getting Ready to Share
> +== Getting Ready to Share: Anatomy of a Patch Series
Shouldn't the title also include the magic word 'Contribution'?
Otherwise the change below may look inconsistent.
> You may have noticed already that the Git project performs its code reviews via
> emailed patches, which are then applied by the maintainer when they are ready
> -and approved by the community. The Git project does not accept patches from
> +and approved by the community. The Git project does not accept contributions from
--
Philip
^ permalink raw reply [flat|nested] 43+ messages in thread
* Re: [PATCH v2 1/5] MyFirstContribution: add "Anatomy of a Patch Series" section
2022-05-12 12:11 ` Philip Oakley
@ 2022-05-12 22:53 ` Philippe Blain
0 siblings, 0 replies; 43+ messages in thread
From: Philippe Blain @ 2022-05-12 22:53 UTC (permalink / raw)
To: Philip Oakley, Philippe Blain via GitGitGadget, git
Cc: Emily Shaffer, Johannes Schindelin, Victoria Dye, Eric Sunshine
Hi Philip,
Le 2022-05-12 à 08:11, Philip Oakley a écrit :
> On 11/05/2022 02:47, Philippe Blain via GitGitGadget wrote:
>> diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
>> index 63a2ef54493..22848f84bec 100644
>> --- a/Documentation/MyFirstContribution.txt
>> +++ b/Documentation/MyFirstContribution.txt
>> @@ -710,13 +710,61 @@ dependencies. `prove` also makes the output nicer.
>> Go ahead and commit this change, as well.
>> [[ready-to-share]]
>> -== Getting Ready to Share
>> +== Getting Ready to Share: Anatomy of a Patch Series
> Shouldn't the title also include the magic word 'Contribution'? Otherwise the change below may look inconsistent.
I don't think so. This section is to introduce "what is a patch series"
to readers that might be reading the word "patch" in a software development context
for the very first time. Patch series are how Git is developped, so the title here should
include these words, I think.
>
>> You may have noticed already that the Git project performs its code reviews via
>> emailed patches, which are then applied by the maintainer when they are ready
>> -and approved by the community. The Git project does not accept patches from
>> +and approved by the community. The Git project does not accept contributions from
the next two words of this sentence are "from pull requests". People that are familiar
with GitHub will probably have heard "contributions" in the context of GitHub "pull requests",
but maybe not "patches". So that's why I changed the wording here.
Thank you for your comments,
Philippe.
^ permalink raw reply [flat|nested] 43+ messages in thread
* [PATCH v2 2/5] MyFirstContribution: add standalone section on cover letter
2022-05-11 1:47 ` [PATCH v2 0/5] Improve MyFirstContribution's GitGitGadget section Philippe Blain via GitGitGadget
2022-05-11 1:47 ` [PATCH v2 1/5] MyFirstContribution: add "Anatomy of a Patch Series" section Philippe Blain via GitGitGadget
@ 2022-05-11 1:47 ` Philippe Blain via GitGitGadget
2022-05-11 10:01 ` Junio C Hamano
2022-05-11 1:47 ` [PATCH v2 3/5] MyFirstContribution: reference "The cover letter" in "Preparing Email" Philippe Blain via GitGitGadget
` (5 subsequent siblings)
7 siblings, 1 reply; 43+ messages in thread
From: Philippe Blain via GitGitGadget @ 2022-05-11 1:47 UTC (permalink / raw)
To: git
Cc: Emily Shaffer, Johannes Schindelin, Victoria Dye, Eric Sunshine,
Philippe Blain, Philippe Blain, Philippe Blain
From: Philippe Blain <levraiphilippeblain@gmail.com>
An explanation of the purpose of the cover letter is included in the
"Sending Patches with git send-email" / "Preparing Email" section but is
missing from the "Sending Patches via GitGitGadget" section.
Add a standalone section "The cover letter" under the "Getting Started:
Anatomy of a Patch Series" header to explain what the cover letter is
used for and to draft the cover letter of the 'psuh' topic used in the
tutorial.
For now we mostly copy content from the "Sending Patches with git
send-email" section but do not adjust that section, nor the GGG section,
to reference the new section. This is done in following commits.
Also, adjust the "Preparing Email" Asciidoc anchor to avoid conflicts.
Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
Documentation/MyFirstContribution.txt | 39 ++++++++++++++++++++++++++-
1 file changed, 38 insertions(+), 1 deletion(-)
diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index 22848f84bec..de62a61771c 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -764,6 +764,43 @@ We can note a few things:
v3]", etc. and sent with a new cover letter, itself a reply to the cover
letter of the previous iteration (more on that below).
+[[cover-letter]]
+=== The cover letter
+
+In addition to an email per patch, the Git community also expects your patches
+to come with a cover letter. This is an important component of change
+submission as it explains to the community from a high level what you're trying
+to do, and why, in a way that's more apparent than just looking at your
+patches.
+
+The title of your cover letter should be something which succinctly covers the
+purpose of your entire topic branch. It's often in the imperative mood, just
+like our commit message titles. Here is how we'll title our series:
+
+---
+Add the 'psuh' command
+---
+
+The body of the cover letter is used to give additional context to reviewers.
+Be sure to explain anything your patches don't make clear on their own, but
+remember that since the cover letter is not recorded in the commit history,
+anything that might be useful to future readers of the repository's history
+should be in your commit messages, not in your cover letter.
+
+Here's an example body for `psuh`:
+
+----
+Our internal metrics indicate widespread interest in the command
+git-psuh - that is, many users are trying to use it, but finding it is
+unavailable, using some unknown workaround instead.
+
+The following handful of patches add the psuh command and implement some
+handy features on top of it.
+
+This patchset is part of the MyFirstContribution tutorial and should not
+be merged.
+----
+
At this point the tutorial diverges, in order to demonstrate two
different methods of formatting your patchset and getting it reviewed.
@@ -1000,7 +1037,7 @@ but want reviewers to look at what they have so far. You can add this flag with
Check and make sure that your patches and cover letter template exist in the
directory you specified - you're nearly ready to send out your review!
-[[cover-letter]]
+[[preparing-cover-letter]]
=== Preparing Email
In addition to an email per patch, the Git community also expects your patches
--
gitgitgadget
^ permalink raw reply related [flat|nested] 43+ messages in thread
* Re: [PATCH v2 2/5] MyFirstContribution: add standalone section on cover letter
2022-05-11 1:47 ` [PATCH v2 2/5] MyFirstContribution: add standalone section on cover letter Philippe Blain via GitGitGadget
@ 2022-05-11 10:01 ` Junio C Hamano
2022-05-11 21:49 ` Philippe Blain
0 siblings, 1 reply; 43+ messages in thread
From: Junio C Hamano @ 2022-05-11 10:01 UTC (permalink / raw)
To: Philippe Blain via GitGitGadget
Cc: git, Emily Shaffer, Johannes Schindelin, Victoria Dye,
Eric Sunshine, Philippe Blain
"Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> writes:
> +The body of the cover letter is used to give additional context to reviewers.
> +Be sure to explain anything your patches don't make clear on their own, but
> +remember that since the cover letter is not recorded in the commit history,
> +anything that might be useful to future readers of the repository's history
> +should be in your commit messages, not in your cover letter.
I agree with only a half of the last sentence.
Things that are useful for "git log" readers should be in the commit
message (but that goes without saying---by definition "git log"
readers are reading commit messages). If that material helps to
understand the overall topic structure by the reviewers, it is not
wrong to have that _also_ in your cover letter. IOW, I sense that
"not in your cover letter" is a bit too strong.
Other than that, I found that 1/5 and 2/5 are very nicely written.
Thanks.
^ permalink raw reply [flat|nested] 43+ messages in thread
* Re: [PATCH v2 2/5] MyFirstContribution: add standalone section on cover letter
2022-05-11 10:01 ` Junio C Hamano
@ 2022-05-11 21:49 ` Philippe Blain
0 siblings, 0 replies; 43+ messages in thread
From: Philippe Blain @ 2022-05-11 21:49 UTC (permalink / raw)
To: Junio C Hamano, Philippe Blain via GitGitGadget
Cc: git, Emily Shaffer, Johannes Schindelin, Victoria Dye,
Eric Sunshine
Hi Junio,
Le 2022-05-11 à 06:01, Junio C Hamano a écrit :
> "Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>> +The body of the cover letter is used to give additional context to reviewers.
>> +Be sure to explain anything your patches don't make clear on their own, but
>> +remember that since the cover letter is not recorded in the commit history,
>> +anything that might be useful to future readers of the repository's history
>> +should be in your commit messages, not in your cover letter.
>
> I agree with only a half of the last sentence.
>
> Things that are useful for "git log" readers should be in the commit
> message (but that goes without saying---by definition "git log"
> readers are reading commit messages). If that material helps to
> understand the overall topic structure by the reviewers, it is not
> wrong to have that _also_ in your cover letter. IOW, I sense that
> "not in your cover letter" is a bit too strong.
OK, I'll tweak that in a v3.
>
> Other than that, I found that 1/5 and 2/5 are very nicely written.
Thanks !:)
^ permalink raw reply [flat|nested] 43+ messages in thread
* [PATCH v2 3/5] MyFirstContribution: reference "The cover letter" in "Preparing Email"
2022-05-11 1:47 ` [PATCH v2 0/5] Improve MyFirstContribution's GitGitGadget section Philippe Blain via GitGitGadget
2022-05-11 1:47 ` [PATCH v2 1/5] MyFirstContribution: add "Anatomy of a Patch Series" section Philippe Blain via GitGitGadget
2022-05-11 1:47 ` [PATCH v2 2/5] MyFirstContribution: add standalone section on cover letter Philippe Blain via GitGitGadget
@ 2022-05-11 1:47 ` Philippe Blain via GitGitGadget
2022-05-11 1:47 ` [PATCH v2 4/5] MyFirstContribution: reference "The cover letter" in GitGitGadget section Philippe Blain via GitGitGadget
` (4 subsequent siblings)
7 siblings, 0 replies; 43+ messages in thread
From: Philippe Blain via GitGitGadget @ 2022-05-11 1:47 UTC (permalink / raw)
To: git
Cc: Emily Shaffer, Johannes Schindelin, Victoria Dye, Eric Sunshine,
Philippe Blain, Philippe Blain, Philippe Blain
From: Philippe Blain <levraiphilippeblain@gmail.com>
The previous commit added a standalone section on the purpose of the
cover letter, drawing inspiration from the existing content of the
"Preparing Email" section.
Adjust "Preparing Email" to reference "The cover letter", to avoid
content duplication.
Also, use the imperative mode for the cover letter subject, as is done
in "The cover letter".
Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
Documentation/MyFirstContribution.txt | 38 +++++++--------------------
1 file changed, 9 insertions(+), 29 deletions(-)
diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index de62a61771c..078b96d674a 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -1040,46 +1040,26 @@ directory you specified - you're nearly ready to send out your review!
[[preparing-cover-letter]]
=== Preparing Email
-In addition to an email per patch, the Git community also expects your patches
-to come with a cover letter, typically with a subject line [PATCH 0/x] (where
-x is the number of patches you're sending). Since you invoked `format-patch`
-with `--cover-letter`, you've already got a template ready. Open it up in your
-favorite editor.
+Since you invoked `format-patch` with `--cover-letter`, you've already got a
+cover letter template ready. Open it up in your favorite editor.
You should see a number of headers present already. Check that your `From:`
-header is correct. Then modify your `Subject:` to something which succinctly
-covers the purpose of your entire topic branch, for example:
+header is correct. Then modify your `Subject:` (see <<cover-letter,above>> for
+how to choose good title for your patch series):
----
-Subject: [PATCH 0/7] adding the 'psuh' command
+Subject: [PATCH 0/7] Add the 'psuh' command
----
Make sure you retain the ``[PATCH 0/X]'' part; that's what indicates to the Git
-community that this email is the beginning of a review, and many reviewers
-filter their email for this type of flag.
+community that this email is the beginning of a patch series, and many
+reviewers filter their email for this type of flag.
You'll need to add some extra parameters when you invoke `git send-email` to add
the cover letter.
-Next you'll have to fill out the body of your cover letter. This is an important
-component of change submission as it explains to the community from a high level
-what you're trying to do, and why, in a way that's more apparent than just
-looking at your diff. Be sure to explain anything your diff doesn't make clear
-on its own.
-
-Here's an example body for `psuh`:
-
-----
-Our internal metrics indicate widespread interest in the command
-git-psuh - that is, many users are trying to use it, but finding it is
-unavailable, using some unknown workaround instead.
-
-The following handful of patches add the psuh command and implement some
-handy features on top of it.
-
-This patchset is part of the MyFirstContribution tutorial and should not
-be merged.
-----
+Next you'll have to fill out the body of your cover letter. Again, see
+<<cover-letter,above>> for what content to include.
The template created by `git format-patch --cover-letter` includes a diffstat.
This gives reviewers a summary of what they're in for when reviewing your topic.
--
gitgitgadget
^ permalink raw reply related [flat|nested] 43+ messages in thread
* [PATCH v2 4/5] MyFirstContribution: reference "The cover letter" in GitGitGadget section
2022-05-11 1:47 ` [PATCH v2 0/5] Improve MyFirstContribution's GitGitGadget section Philippe Blain via GitGitGadget
` (2 preceding siblings ...)
2022-05-11 1:47 ` [PATCH v2 3/5] MyFirstContribution: reference "The cover letter" in "Preparing Email" Philippe Blain via GitGitGadget
@ 2022-05-11 1:47 ` Philippe Blain via GitGitGadget
2022-05-11 1:47 ` [PATCH v2 5/5] MyFirstContribution: drop PR description for GGG single-patch contributions Philippe Blain via GitGitGadget
` (3 subsequent siblings)
7 siblings, 0 replies; 43+ messages in thread
From: Philippe Blain via GitGitGadget @ 2022-05-11 1:47 UTC (permalink / raw)
To: git
Cc: Emily Shaffer, Johannes Schindelin, Victoria Dye, Eric Sunshine,
Philippe Blain, Philippe Blain, Philippe Blain
From: Philippe Blain <levraiphilippeblain@gmail.com>
The "Sending Patches via GitGitGadget" section mentions that the PR
title and description will be used as the cover letter, but does not
explain what is a cover letter or what should be included in it.
Refer readers to the new "The cover letter" section added in a previous
commit.
Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
Documentation/MyFirstContribution.txt | 8 ++++++--
1 file changed, 6 insertions(+), 2 deletions(-)
diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index 078b96d674a..728dc437854 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -893,8 +893,12 @@ https://github.com/gitgitgadget/git and open a PR either with the "New pull
request" button or the convenient "Compare & pull request" button that may
appear with the name of your newly pushed branch.
-Review the PR's title and description, as it's used by GitGitGadget as the cover
-letter for your change. When you're happy, submit your pull request.
+Review the PR's title and description, as they're used by GitGitGadget
+respectively as the subject and body of the cover letter for your change. Refer
+to <<cover-letter,"The cover letter">> above for advice on how to title your
+submission and what content to include in the description.
+
+When you're happy, submit your pull request.
[[run-ci-ggg]]
=== Running CI and Getting Ready to Send
--
gitgitgadget
^ permalink raw reply related [flat|nested] 43+ messages in thread
* [PATCH v2 5/5] MyFirstContribution: drop PR description for GGG single-patch contributions
2022-05-11 1:47 ` [PATCH v2 0/5] Improve MyFirstContribution's GitGitGadget section Philippe Blain via GitGitGadget
` (3 preceding siblings ...)
2022-05-11 1:47 ` [PATCH v2 4/5] MyFirstContribution: reference "The cover letter" in GitGitGadget section Philippe Blain via GitGitGadget
@ 2022-05-11 1:47 ` Philippe Blain via GitGitGadget
2022-05-11 10:11 ` [PATCH v2 0/5] Improve MyFirstContribution's GitGitGadget section Junio C Hamano
` (2 subsequent siblings)
7 siblings, 0 replies; 43+ messages in thread
From: Philippe Blain via GitGitGadget @ 2022-05-11 1:47 UTC (permalink / raw)
To: git
Cc: Emily Shaffer, Johannes Schindelin, Victoria Dye, Eric Sunshine,
Philippe Blain, Philippe Blain, Philippe Blain
From: Philippe Blain <levraiphilippeblain@gmail.com>
By default, GitHub prefills the PR description using the commit message
for single-commit PRs. This results in a duplicate commit message below
the three-dash line if the contributor does not empty out the PR
description before submitting, which adds noise for reviewers.
Add a note to that effect in MyFirstContribution.txt.
This partly addresses:
https://github.com/gitgitgadget/gitgitgadget/issues/340
Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
Documentation/MyFirstContribution.txt | 10 ++++++++++
1 file changed, 10 insertions(+)
diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index 728dc437854..01b9e5db117 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -898,6 +898,16 @@ respectively as the subject and body of the cover letter for your change. Refer
to <<cover-letter,"The cover letter">> above for advice on how to title your
submission and what content to include in the description.
+NOTE: For single-patch contributions, your commit message should already be
+meaningful and explain at a high level the purpose (what is happening and why)
+of your patch, so you usually do not need any additional context. In that case,
+remove the PR description that GitHub automatically generates from your commit
+message (your PR description should be empty). If you do need to supply even
+more context, you can do so in that space and it will be appended to the email
+that GitGitGadget will send, between the three-dash line and the diffstat
+(see <<single-patch,Bonus Chapter: One-Patch Changes>> for how this looks once
+submitted).
+
When you're happy, submit your pull request.
[[run-ci-ggg]]
--
gitgitgadget
^ permalink raw reply related [flat|nested] 43+ messages in thread
* Re: [PATCH v2 0/5] Improve MyFirstContribution's GitGitGadget section
2022-05-11 1:47 ` [PATCH v2 0/5] Improve MyFirstContribution's GitGitGadget section Philippe Blain via GitGitGadget
` (4 preceding siblings ...)
2022-05-11 1:47 ` [PATCH v2 5/5] MyFirstContribution: drop PR description for GGG single-patch contributions Philippe Blain via GitGitGadget
@ 2022-05-11 10:11 ` Junio C Hamano
2022-05-11 17:45 ` Victoria Dye
2022-05-12 23:43 ` [PATCH v3 " Philippe Blain via GitGitGadget
7 siblings, 0 replies; 43+ messages in thread
From: Junio C Hamano @ 2022-05-11 10:11 UTC (permalink / raw)
To: Philippe Blain via GitGitGadget
Cc: git, Emily Shaffer, Johannes Schindelin, Victoria Dye,
Eric Sunshine, Philippe Blain
"Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> writes:
> Thanks a lot for the reviews! Here is an updated version.
Thanks a lot for the patches. I made a small comment or two, but
other than those, everything looked good.
Will queue.
^ permalink raw reply [flat|nested] 43+ messages in thread
* Re: [PATCH v2 0/5] Improve MyFirstContribution's GitGitGadget section
2022-05-11 1:47 ` [PATCH v2 0/5] Improve MyFirstContribution's GitGitGadget section Philippe Blain via GitGitGadget
` (5 preceding siblings ...)
2022-05-11 10:11 ` [PATCH v2 0/5] Improve MyFirstContribution's GitGitGadget section Junio C Hamano
@ 2022-05-11 17:45 ` Victoria Dye
2022-05-12 23:43 ` [PATCH v3 " Philippe Blain via GitGitGadget
7 siblings, 0 replies; 43+ messages in thread
From: Victoria Dye @ 2022-05-11 17:45 UTC (permalink / raw)
To: Philippe Blain via GitGitGadget, git
Cc: Emily Shaffer, Johannes Schindelin, Eric Sunshine, Philippe Blain
Philippe Blain via GitGitGadget wrote:
> Thanks a lot for the reviews! Here is an updated version.
>
> Changes since v1:
>
> * Based on v1 feedback, instead of reusing the 'git send-email' content
> verbatim in the GGG section, added a new section and reference it in both
> 'git send-email' and GGG sections. (patches 1/5-4/5)
> * In patch 5/5 (patch 3/3 in v1), tweak wording and add a reference to the
> "Bonus Chapter: One-Patch Changes" section.
>
This version addresses all of my earlier comments, and overall looks good to
me. Thanks again for updating this documentation!
> v1: Two small improvements to the MyFirstContribution tutorial:
>
> * Describe the purpose of the cover letter in that section also, and give
> an example just as in the 'git send-email' section
> * Instruct contributors to drop the GitHub-generated PR description for
> single patch contributions.
>
> Philippe Blain (5):
> MyFirstContribution: add "Anatomy of a Patch Series" section
> MyFirstContribution: add standalone section on cover letter
> MyFirstContribution: reference "The cover letter" in "Preparing Email"
> MyFirstContribution: reference "The cover letter" in GitGitGadget
> section
> MyFirstContribution: drop PR description for GGG single-patch
> contributions
>
> Documentation/MyFirstContribution.txt | 149 ++++++++++++++++++++------
> 1 file changed, 114 insertions(+), 35 deletions(-)
>
>
> base-commit: 6cd33dceed60949e2dbc32e3f0f5e67c4c882e1e
> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1226%2Fphil-blain%2Fmyfirst-contrib-single-patch-ggg-v2
> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1226/phil-blain/myfirst-contrib-single-patch-ggg-v2
> Pull-Request: https://github.com/gitgitgadget/git/pull/1226
>
> Range-diff vs v1:
>
> -: ----------- > 1: 59af7e5e5ad MyFirstContribution: add "Anatomy of a Patch Series" section
> -: ----------- > 2: 9552d80a80d MyFirstContribution: add standalone section on cover letter
> 1: 7e84d5b286d ! 3: d7699289ea6 MyFirstContribution: move cover letter description to a separate file
> @@ Metadata
> Author: Philippe Blain <levraiphilippeblain@gmail.com>
>
> ## Commit message ##
> - MyFirstContribution: move cover letter description to a separate file
> + MyFirstContribution: reference "The cover letter" in "Preparing Email"
>
> - In a subsequent commit we want to reuse the explanation of the purpose of
> - The cover letter form the "Sending Patches with git send-email" section
> - in the "Sending Patches via GitGitGadget" section.
> + The previous commit added a standalone section on the purpose of the
> + cover letter, drawing inspiration from the existing content of the
> + "Preparing Email" section.
>
> - To avoid text duplication, move this explanation to a separate file and
> - include it in MyFirstContribution.txt.
> + Adjust "Preparing Email" to reference "The cover letter", to avoid
> + content duplication.
>
> - Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
> + Also, use the imperative mode for the cover letter subject, as is done
> + in "The cover letter".
>
> - ## Documentation/MyFirstContribution-coverletter.txt (new) ##
> -@@
> -+This is an important component of change submission as it explains to the
> -+community from a high level what you're trying to do, and why, in a way that's
> -+more apparent than just looking at your diff. Be sure to explain anything your
> -+diff doesn't make clear on its own.
> -+
> -+Here's an example body for `psuh`:
> -+
> -+----
> -+Our internal metrics indicate widespread interest in the command
> -+git-psuh - that is, many users are trying to use it, but finding it is
> -+unavailable, using some unknown workaround instead.
> -+
> -+The following handful of patches add the psuh command and implement some
> -+handy features on top of it.
> -+
> -+This patchset is part of the MyFirstContribution tutorial and should not
> -+be merged.
> -+----
> + Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
>
> ## Documentation/MyFirstContribution.txt ##
> -@@ Documentation/MyFirstContribution.txt: filter their email for this type of flag.
> +@@ Documentation/MyFirstContribution.txt: directory you specified - you're nearly ready to send out your review!
> + [[preparing-cover-letter]]
> + === Preparing Email
> +
> +-In addition to an email per patch, the Git community also expects your patches
> +-to come with a cover letter, typically with a subject line [PATCH 0/x] (where
> +-x is the number of patches you're sending). Since you invoked `format-patch`
> +-with `--cover-letter`, you've already got a template ready. Open it up in your
> +-favorite editor.
> ++Since you invoked `format-patch` with `--cover-letter`, you've already got a
> ++cover letter template ready. Open it up in your favorite editor.
> +
> + You should see a number of headers present already. Check that your `From:`
> +-header is correct. Then modify your `Subject:` to something which succinctly
> +-covers the purpose of your entire topic branch, for example:
> ++header is correct. Then modify your `Subject:` (see <<cover-letter,above>> for
> ++how to choose good title for your patch series):
> +
> + ----
> +-Subject: [PATCH 0/7] adding the 'psuh' command
> ++Subject: [PATCH 0/7] Add the 'psuh' command
> + ----
> +
> + Make sure you retain the ``[PATCH 0/X]'' part; that's what indicates to the Git
> +-community that this email is the beginning of a review, and many reviewers
> +-filter their email for this type of flag.
> ++community that this email is the beginning of a patch series, and many
> ++reviewers filter their email for this type of flag.
> +
> You'll need to add some extra parameters when you invoke `git send-email` to add
> the cover letter.
>
> @@ Documentation/MyFirstContribution.txt: filter their email for this type of flag.
> -This patchset is part of the MyFirstContribution tutorial and should not
> -be merged.
> -----
> -+Next you'll have to fill out the body of your cover letter.
> -+include::MyFirstContribution-coverletter.txt[]
> ++Next you'll have to fill out the body of your cover letter. Again, see
> ++<<cover-letter,above>> for what content to include.
>
> The template created by `git format-patch --cover-letter` includes a diffstat.
> This gives reviewers a summary of what they're in for when reviewing your topic.
> 2: afb80b8e9ee ! 4: f6034b0964b MyFirstContribution: also explain cover letter in GitGitGadget section
> @@ Metadata
> Author: Philippe Blain <levraiphilippeblain@gmail.com>
>
> ## Commit message ##
> - MyFirstContribution: also explain cover letter in GitGitGadget section
> + MyFirstContribution: reference "The cover letter" in GitGitGadget section
>
> The "Sending Patches via GitGitGadget" section mentions that the PR
> title and description will be used as the cover letter, but does not
> explain what is a cover letter or what should be included in it.
>
> - Mention the purpose of the cover letter in that section, and give
> - examples for the title and description, leveraging the excerpt extracted
> - from the "Sending Patches with git send-email" section in the previous
> + Refer readers to the new "The cover letter" section added in a previous
> commit.
>
> Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
> @@ Documentation/MyFirstContribution.txt: https://github.com/gitgitgadget/git and o
>
> -Review the PR's title and description, as it's used by GitGitGadget as the cover
> -letter for your change. When you're happy, submit your pull request.
> -+Review the PR's title and description, as they're used by GitGitGadget as the
> -+cover letter for your change. The cover letter describes your proposed
> -+contribution as a whole and is ideal to mention any context that might be
> -+useful for reviewers. The title of your PR should be something which
> -+succinctly covers the purpose of your entire topic branch, for example:
> -+
> -+----
> -+Adding the 'psuh' command
> -+----
> -+
> -+Your PR's description will used as the body of the cover letter.
> -+include::MyFirstContribution-coverletter.txt[]
> ++Review the PR's title and description, as they're used by GitGitGadget
> ++respectively as the subject and body of the cover letter for your change. Refer
> ++to <<cover-letter,"The cover letter">> above for advice on how to title your
> ++submission and what content to include in the description.
> +
> +When you're happy, submit your pull request.
>
> 3: 2f6ecbf2601 ! 5: 33256c6b4ba MyFirstContribution: drop PR description for GGG single-patch contributions
> @@ Commit message
> Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
>
> ## Documentation/MyFirstContribution.txt ##
> -@@ Documentation/MyFirstContribution.txt: Adding the 'psuh' command
> - Your PR's description will used as the body of the cover letter.
> - include::MyFirstContribution-coverletter.txt[]
> +@@ Documentation/MyFirstContribution.txt: respectively as the subject and body of the cover letter for your change. Refer
> + to <<cover-letter,"The cover letter">> above for advice on how to title your
> + submission and what content to include in the description.
>
> +NOTE: For single-patch contributions, your commit message should already be
> +meaningful and explain at a high level the purpose (what is happening and why)
> @@ Documentation/MyFirstContribution.txt: Adding the 'psuh' command
> +remove the PR description that GitHub automatically generates from your commit
> +message (your PR description should be empty). If you do need to supply even
> +more context, you can do so in that space and it will be appended to the email
> -+that GitGitGadget will send, separately from your commit message.
> ++that GitGitGadget will send, between the three-dash line and the diffstat
> ++(see <<single-patch,Bonus Chapter: One-Patch Changes>> for how this looks once
> ++submitted).
> +
> When you're happy, submit your pull request.
>
>
^ permalink raw reply [flat|nested] 43+ messages in thread
* [PATCH v3 0/5] Improve MyFirstContribution's GitGitGadget section
2022-05-11 1:47 ` [PATCH v2 0/5] Improve MyFirstContribution's GitGitGadget section Philippe Blain via GitGitGadget
` (6 preceding siblings ...)
2022-05-11 17:45 ` Victoria Dye
@ 2022-05-12 23:43 ` Philippe Blain via GitGitGadget
2022-05-12 23:43 ` [PATCH v3 1/5] MyFirstContribution: add "Anatomy of a Patch Series" section Philippe Blain via GitGitGadget
` (5 more replies)
7 siblings, 6 replies; 43+ messages in thread
From: Philippe Blain via GitGitGadget @ 2022-05-12 23:43 UTC (permalink / raw)
To: git
Cc: Emily Shaffer, Johannes Schindelin, Victoria Dye, Eric Sunshine,
Philippe Blain, Bagas Sanjaya, Philip Oakley, Philippe Blain
Changes since v2:
* tweaked 2/5 following Junio's comments (added more details, tweaked the
wording and added a note about single patch series).
v2: Thanks a lot for the reviews! Here is an updated version.
Changes since v1:
* Based on v1 feedback, instead of reusing the 'git send-email' content
verbatim in the GGG section, added a new section and reference it in both
'git send-email' and GGG sections. (patches 1/5-4/5)
* In patch 5/5 (patch 3/3 in v1), tweak wording and add a reference to the
"Bonus Chapter: One-Patch Changes" section.
v1: Two small improvements to the MyFirstContribution tutorial:
* Describe the purpose of the cover letter in that section also, and give
an example just as in the 'git send-email' section
* Instruct contributors to drop the GitHub-generated PR description for
single patch contributions.
Philippe Blain (5):
MyFirstContribution: add "Anatomy of a Patch Series" section
MyFirstContribution: add standalone section on cover letter
MyFirstContribution: reference "The cover letter" in "Preparing Email"
MyFirstContribution: reference "The cover letter" in GitGitGadget
section
MyFirstContribution: drop PR description for GGG single-patch
contributions
Documentation/MyFirstContribution.txt | 155 ++++++++++++++++++++------
1 file changed, 120 insertions(+), 35 deletions(-)
base-commit: 6cd33dceed60949e2dbc32e3f0f5e67c4c882e1e
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1226%2Fphil-blain%2Fmyfirst-contrib-single-patch-ggg-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1226/phil-blain/myfirst-contrib-single-patch-ggg-v3
Pull-Request: https://github.com/gitgitgadget/git/pull/1226
Range-diff vs v2:
1: 59af7e5e5ad = 1: 59af7e5e5ad MyFirstContribution: add "Anatomy of a Patch Series" section
2: 9552d80a80d ! 2: ee3238f5a91 MyFirstContribution: add standalone section on cover letter
@@ Commit message
## Documentation/MyFirstContribution.txt ##
@@ Documentation/MyFirstContribution.txt: We can note a few things:
- v3]", etc. and sent with a new cover letter, itself a reply to the cover
- letter of the previous iteration (more on that below).
-
+ _n_-commit series.
+ - Each patch is sent as a reply to an introductory email called the _cover
+ letter_ of the series, prefixed "[PATCH 0/_n_]".
+-- Subsequent iterations of the patch series are labelled "[PATCH v2]", "[PATCH
+- v3]", etc. and sent with a new cover letter, itself a reply to the cover
+- letter of the previous iteration (more on that below).
++- Subsequent iterations of the patch series are labelled "PATCH v2", "PATCH
++ v3", etc. in place of "PATCH". For example, "[PATCH v2 1/3]" would be the first of
++ three patches in the second iteration. Each iteration is sent with a new cover
++ letter (like "[PATCH v2 0/3]" above), itself a reply to the cover letter of the
++ previous iteration (more on that below).
++
++NOTE: A single-patch topic is sent with "[PATCH]", "[PATCH v2]", etc. without
++_i_/_n_ numbering (in the above thread overview, no single-patch topic appears,
++though).
++
+[[cover-letter]]
+=== The cover letter
+
@@ Documentation/MyFirstContribution.txt: We can note a few things:
+Be sure to explain anything your patches don't make clear on their own, but
+remember that since the cover letter is not recorded in the commit history,
+anything that might be useful to future readers of the repository's history
-+should be in your commit messages, not in your cover letter.
++should also be in your commit messages.
+
+Here's an example body for `psuh`:
+
@@ Documentation/MyFirstContribution.txt: We can note a few things:
+This patchset is part of the MyFirstContribution tutorial and should not
+be merged.
+----
-+
+
At this point the tutorial diverges, in order to demonstrate two
different methods of formatting your patchset and getting it reviewed.
-
@@ Documentation/MyFirstContribution.txt: but want reviewers to look at what they have so far. You can add this flag with
Check and make sure that your patches and cover letter template exist in the
directory you specified - you're nearly ready to send out your review!
3: d7699289ea6 = 3: 2caec6e619a MyFirstContribution: reference "The cover letter" in "Preparing Email"
4: f6034b0964b = 4: 02598d431e0 MyFirstContribution: reference "The cover letter" in GitGitGadget section
5: 33256c6b4ba = 5: 76bcb6612e4 MyFirstContribution: drop PR description for GGG single-patch contributions
--
gitgitgadget
^ permalink raw reply [flat|nested] 43+ messages in thread
* [PATCH v3 1/5] MyFirstContribution: add "Anatomy of a Patch Series" section
2022-05-12 23:43 ` [PATCH v3 " Philippe Blain via GitGitGadget
@ 2022-05-12 23:43 ` Philippe Blain via GitGitGadget
2022-05-12 23:43 ` [PATCH v3 2/5] MyFirstContribution: add standalone section on cover letter Philippe Blain via GitGitGadget
` (4 subsequent siblings)
5 siblings, 0 replies; 43+ messages in thread
From: Philippe Blain via GitGitGadget @ 2022-05-12 23:43 UTC (permalink / raw)
To: git
Cc: Emily Shaffer, Johannes Schindelin, Victoria Dye, Eric Sunshine,
Philippe Blain, Bagas Sanjaya, Philip Oakley, Philippe Blain,
Philippe Blain
From: Philippe Blain <levraiphilippeblain@gmail.com>
Before describing how to send patches to the mailing list either with
GitGitGadget or 'git send-email', the MyFirstContribution tutorial
includes a small "Getting Ready to Share" section where the two
different methods are briefly introduced.
Use this section to also describe what a patch series looks like once
submitted, so that readers get an understanding of the end result before
diving into how to accomplish that end result.
Start by copying the "thread overview" section of a recent contribution
from the public-inbox web UI and explaining how each commit is a
separate mail, and point out the cover letter.
Subsequent commits will move the existing description of the purpose of
the cover letter from the 'git send-email' section to this "anatomy"
section.
Also, change the wording in the introductory paragraph to use
"contributions" instead of "patches", since this makes more sense when
talking about GitHub pull requests.
Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
Documentation/MyFirstContribution.txt | 54 +++++++++++++++++++++++++--
1 file changed, 51 insertions(+), 3 deletions(-)
diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index 63a2ef54493..22848f84bec 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -710,13 +710,61 @@ dependencies. `prove` also makes the output nicer.
Go ahead and commit this change, as well.
[[ready-to-share]]
-== Getting Ready to Share
+== Getting Ready to Share: Anatomy of a Patch Series
You may have noticed already that the Git project performs its code reviews via
emailed patches, which are then applied by the maintainer when they are ready
-and approved by the community. The Git project does not accept patches from
+and approved by the community. The Git project does not accept contributions from
pull requests, and the patches emailed for review need to be formatted a
-specific way. At this point the tutorial diverges, in order to demonstrate two
+specific way.
+
+:patch-series: https://lore.kernel.org/git/pull.1218.git.git.1645209647.gitgitgadget@gmail.com/
+:lore: https://lore.kernel.org/git/
+
+Before taking a look at how to convert your commits into emailed patches,
+let's analyze what the end result, a "patch series", looks like. Here is an
+{patch-series}[example] of the summary view for a patch series on the web interface of
+the {lore}[Git mailing list archive]:
+
+----
+2022-02-18 18:40 [PATCH 0/3] libify reflog John Cai via GitGitGadget
+2022-02-18 18:40 ` [PATCH 1/3] reflog: libify delete reflog function and helpers John Cai via GitGitGadget
+2022-02-18 19:10 ` Ævar Arnfjörð Bjarmason [this message]
+2022-02-18 19:39 ` Taylor Blau
+2022-02-18 19:48 ` Ævar Arnfjörð Bjarmason
+2022-02-18 19:35 ` Taylor Blau
+2022-02-21 1:43 ` John Cai
+2022-02-21 1:50 ` Taylor Blau
+2022-02-23 19:50 ` John Cai
+2022-02-18 20:00 ` // other replies ellided
+2022-02-18 18:40 ` [PATCH 2/3] reflog: call reflog_delete from reflog.c John Cai via GitGitGadget
+2022-02-18 19:15 ` Ævar Arnfjörð Bjarmason
+2022-02-18 20:26 ` Junio C Hamano
+2022-02-18 18:40 ` [PATCH 3/3] stash: call reflog_delete from reflog.c John Cai via GitGitGadget
+2022-02-18 19:20 ` Ævar Arnfjörð Bjarmason
+2022-02-19 0:21 ` Taylor Blau
+2022-02-22 2:36 ` John Cai
+2022-02-22 10:51 ` Ævar Arnfjörð Bjarmason
+2022-02-18 19:29 ` [PATCH 0/3] libify reflog Ævar Arnfjörð Bjarmason
+2022-02-22 18:30 ` [PATCH v2 0/3] libify reflog John Cai via GitGitGadget
+2022-02-22 18:30 ` [PATCH v2 1/3] stash: add test to ensure reflog --rewrite --updatref behavior John Cai via GitGitGadget
+2022-02-23 8:54 ` Ævar Arnfjörð Bjarmason
+2022-02-23 21:27 ` Junio C Hamano
+// continued
+----
+
+We can note a few things:
+
+- Each commit is sent as a separate email, with the commit message title as
+ subject, prefixed with "[PATCH _i_/_n_]" for the _i_-th commit of an
+ _n_-commit series.
+- Each patch is sent as a reply to an introductory email called the _cover
+ letter_ of the series, prefixed "[PATCH 0/_n_]".
+- Subsequent iterations of the patch series are labelled "[PATCH v2]", "[PATCH
+ v3]", etc. and sent with a new cover letter, itself a reply to the cover
+ letter of the previous iteration (more on that below).
+
+At this point the tutorial diverges, in order to demonstrate two
different methods of formatting your patchset and getting it reviewed.
The first method to be covered is GitGitGadget, which is useful for those
--
gitgitgadget
^ permalink raw reply related [flat|nested] 43+ messages in thread
* [PATCH v3 2/5] MyFirstContribution: add standalone section on cover letter
2022-05-12 23:43 ` [PATCH v3 " Philippe Blain via GitGitGadget
2022-05-12 23:43 ` [PATCH v3 1/5] MyFirstContribution: add "Anatomy of a Patch Series" section Philippe Blain via GitGitGadget
@ 2022-05-12 23:43 ` Philippe Blain via GitGitGadget
2022-05-12 23:43 ` [PATCH v3 3/5] MyFirstContribution: reference "The cover letter" in "Preparing Email" Philippe Blain via GitGitGadget
` (3 subsequent siblings)
5 siblings, 0 replies; 43+ messages in thread
From: Philippe Blain via GitGitGadget @ 2022-05-12 23:43 UTC (permalink / raw)
To: git
Cc: Emily Shaffer, Johannes Schindelin, Victoria Dye, Eric Sunshine,
Philippe Blain, Bagas Sanjaya, Philip Oakley, Philippe Blain,
Philippe Blain
From: Philippe Blain <levraiphilippeblain@gmail.com>
An explanation of the purpose of the cover letter is included in the
"Sending Patches with git send-email" / "Preparing Email" section but is
missing from the "Sending Patches via GitGitGadget" section.
Add a standalone section "The cover letter" under the "Getting Started:
Anatomy of a Patch Series" header to explain what the cover letter is
used for and to draft the cover letter of the 'psuh' topic used in the
tutorial.
For now we mostly copy content from the "Sending Patches with git
send-email" section but do not adjust that section, nor the GGG section,
to reference the new section. This is done in following commits.
Also, adjust the "Preparing Email" Asciidoc anchor to avoid conflicts.
Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
Documentation/MyFirstContribution.txt | 51 ++++++++++++++++++++++++---
1 file changed, 47 insertions(+), 4 deletions(-)
diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index 22848f84bec..94f722d4b7f 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -760,9 +760,52 @@ We can note a few things:
_n_-commit series.
- Each patch is sent as a reply to an introductory email called the _cover
letter_ of the series, prefixed "[PATCH 0/_n_]".
-- Subsequent iterations of the patch series are labelled "[PATCH v2]", "[PATCH
- v3]", etc. and sent with a new cover letter, itself a reply to the cover
- letter of the previous iteration (more on that below).
+- Subsequent iterations of the patch series are labelled "PATCH v2", "PATCH
+ v3", etc. in place of "PATCH". For example, "[PATCH v2 1/3]" would be the first of
+ three patches in the second iteration. Each iteration is sent with a new cover
+ letter (like "[PATCH v2 0/3]" above), itself a reply to the cover letter of the
+ previous iteration (more on that below).
+
+NOTE: A single-patch topic is sent with "[PATCH]", "[PATCH v2]", etc. without
+_i_/_n_ numbering (in the above thread overview, no single-patch topic appears,
+though).
+
+[[cover-letter]]
+=== The cover letter
+
+In addition to an email per patch, the Git community also expects your patches
+to come with a cover letter. This is an important component of change
+submission as it explains to the community from a high level what you're trying
+to do, and why, in a way that's more apparent than just looking at your
+patches.
+
+The title of your cover letter should be something which succinctly covers the
+purpose of your entire topic branch. It's often in the imperative mood, just
+like our commit message titles. Here is how we'll title our series:
+
+---
+Add the 'psuh' command
+---
+
+The body of the cover letter is used to give additional context to reviewers.
+Be sure to explain anything your patches don't make clear on their own, but
+remember that since the cover letter is not recorded in the commit history,
+anything that might be useful to future readers of the repository's history
+should also be in your commit messages.
+
+Here's an example body for `psuh`:
+
+----
+Our internal metrics indicate widespread interest in the command
+git-psuh - that is, many users are trying to use it, but finding it is
+unavailable, using some unknown workaround instead.
+
+The following handful of patches add the psuh command and implement some
+handy features on top of it.
+
+This patchset is part of the MyFirstContribution tutorial and should not
+be merged.
+----
At this point the tutorial diverges, in order to demonstrate two
different methods of formatting your patchset and getting it reviewed.
@@ -1000,7 +1043,7 @@ but want reviewers to look at what they have so far. You can add this flag with
Check and make sure that your patches and cover letter template exist in the
directory you specified - you're nearly ready to send out your review!
-[[cover-letter]]
+[[preparing-cover-letter]]
=== Preparing Email
In addition to an email per patch, the Git community also expects your patches
--
gitgitgadget
^ permalink raw reply related [flat|nested] 43+ messages in thread
* [PATCH v3 3/5] MyFirstContribution: reference "The cover letter" in "Preparing Email"
2022-05-12 23:43 ` [PATCH v3 " Philippe Blain via GitGitGadget
2022-05-12 23:43 ` [PATCH v3 1/5] MyFirstContribution: add "Anatomy of a Patch Series" section Philippe Blain via GitGitGadget
2022-05-12 23:43 ` [PATCH v3 2/5] MyFirstContribution: add standalone section on cover letter Philippe Blain via GitGitGadget
@ 2022-05-12 23:43 ` Philippe Blain via GitGitGadget
2022-05-12 23:43 ` [PATCH v3 4/5] MyFirstContribution: reference "The cover letter" in GitGitGadget section Philippe Blain via GitGitGadget
` (2 subsequent siblings)
5 siblings, 0 replies; 43+ messages in thread
From: Philippe Blain via GitGitGadget @ 2022-05-12 23:43 UTC (permalink / raw)
To: git
Cc: Emily Shaffer, Johannes Schindelin, Victoria Dye, Eric Sunshine,
Philippe Blain, Bagas Sanjaya, Philip Oakley, Philippe Blain,
Philippe Blain
From: Philippe Blain <levraiphilippeblain@gmail.com>
The previous commit added a standalone section on the purpose of the
cover letter, drawing inspiration from the existing content of the
"Preparing Email" section.
Adjust "Preparing Email" to reference "The cover letter", to avoid
content duplication.
Also, use the imperative mode for the cover letter subject, as is done
in "The cover letter".
Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
Documentation/MyFirstContribution.txt | 38 +++++++--------------------
1 file changed, 9 insertions(+), 29 deletions(-)
diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index 94f722d4b7f..f6ee5b8b1ae 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -1046,46 +1046,26 @@ directory you specified - you're nearly ready to send out your review!
[[preparing-cover-letter]]
=== Preparing Email
-In addition to an email per patch, the Git community also expects your patches
-to come with a cover letter, typically with a subject line [PATCH 0/x] (where
-x is the number of patches you're sending). Since you invoked `format-patch`
-with `--cover-letter`, you've already got a template ready. Open it up in your
-favorite editor.
+Since you invoked `format-patch` with `--cover-letter`, you've already got a
+cover letter template ready. Open it up in your favorite editor.
You should see a number of headers present already. Check that your `From:`
-header is correct. Then modify your `Subject:` to something which succinctly
-covers the purpose of your entire topic branch, for example:
+header is correct. Then modify your `Subject:` (see <<cover-letter,above>> for
+how to choose good title for your patch series):
----
-Subject: [PATCH 0/7] adding the 'psuh' command
+Subject: [PATCH 0/7] Add the 'psuh' command
----
Make sure you retain the ``[PATCH 0/X]'' part; that's what indicates to the Git
-community that this email is the beginning of a review, and many reviewers
-filter their email for this type of flag.
+community that this email is the beginning of a patch series, and many
+reviewers filter their email for this type of flag.
You'll need to add some extra parameters when you invoke `git send-email` to add
the cover letter.
-Next you'll have to fill out the body of your cover letter. This is an important
-component of change submission as it explains to the community from a high level
-what you're trying to do, and why, in a way that's more apparent than just
-looking at your diff. Be sure to explain anything your diff doesn't make clear
-on its own.
-
-Here's an example body for `psuh`:
-
-----
-Our internal metrics indicate widespread interest in the command
-git-psuh - that is, many users are trying to use it, but finding it is
-unavailable, using some unknown workaround instead.
-
-The following handful of patches add the psuh command and implement some
-handy features on top of it.
-
-This patchset is part of the MyFirstContribution tutorial and should not
-be merged.
-----
+Next you'll have to fill out the body of your cover letter. Again, see
+<<cover-letter,above>> for what content to include.
The template created by `git format-patch --cover-letter` includes a diffstat.
This gives reviewers a summary of what they're in for when reviewing your topic.
--
gitgitgadget
^ permalink raw reply related [flat|nested] 43+ messages in thread
* [PATCH v3 4/5] MyFirstContribution: reference "The cover letter" in GitGitGadget section
2022-05-12 23:43 ` [PATCH v3 " Philippe Blain via GitGitGadget
` (2 preceding siblings ...)
2022-05-12 23:43 ` [PATCH v3 3/5] MyFirstContribution: reference "The cover letter" in "Preparing Email" Philippe Blain via GitGitGadget
@ 2022-05-12 23:43 ` Philippe Blain via GitGitGadget
2022-05-12 23:43 ` [PATCH v3 5/5] MyFirstContribution: drop PR description for GGG single-patch contributions Philippe Blain via GitGitGadget
2022-05-19 21:49 ` [PATCH v3 0/5] Improve MyFirstContribution's GitGitGadget section Junio C Hamano
5 siblings, 0 replies; 43+ messages in thread
From: Philippe Blain via GitGitGadget @ 2022-05-12 23:43 UTC (permalink / raw)
To: git
Cc: Emily Shaffer, Johannes Schindelin, Victoria Dye, Eric Sunshine,
Philippe Blain, Bagas Sanjaya, Philip Oakley, Philippe Blain,
Philippe Blain
From: Philippe Blain <levraiphilippeblain@gmail.com>
The "Sending Patches via GitGitGadget" section mentions that the PR
title and description will be used as the cover letter, but does not
explain what is a cover letter or what should be included in it.
Refer readers to the new "The cover letter" section added in a previous
commit.
Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
Documentation/MyFirstContribution.txt | 8 ++++++--
1 file changed, 6 insertions(+), 2 deletions(-)
diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index f6ee5b8b1ae..9eb2dfec959 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -899,8 +899,12 @@ https://github.com/gitgitgadget/git and open a PR either with the "New pull
request" button or the convenient "Compare & pull request" button that may
appear with the name of your newly pushed branch.
-Review the PR's title and description, as it's used by GitGitGadget as the cover
-letter for your change. When you're happy, submit your pull request.
+Review the PR's title and description, as they're used by GitGitGadget
+respectively as the subject and body of the cover letter for your change. Refer
+to <<cover-letter,"The cover letter">> above for advice on how to title your
+submission and what content to include in the description.
+
+When you're happy, submit your pull request.
[[run-ci-ggg]]
=== Running CI and Getting Ready to Send
--
gitgitgadget
^ permalink raw reply related [flat|nested] 43+ messages in thread
* [PATCH v3 5/5] MyFirstContribution: drop PR description for GGG single-patch contributions
2022-05-12 23:43 ` [PATCH v3 " Philippe Blain via GitGitGadget
` (3 preceding siblings ...)
2022-05-12 23:43 ` [PATCH v3 4/5] MyFirstContribution: reference "The cover letter" in GitGitGadget section Philippe Blain via GitGitGadget
@ 2022-05-12 23:43 ` Philippe Blain via GitGitGadget
2022-05-19 21:49 ` [PATCH v3 0/5] Improve MyFirstContribution's GitGitGadget section Junio C Hamano
5 siblings, 0 replies; 43+ messages in thread
From: Philippe Blain via GitGitGadget @ 2022-05-12 23:43 UTC (permalink / raw)
To: git
Cc: Emily Shaffer, Johannes Schindelin, Victoria Dye, Eric Sunshine,
Philippe Blain, Bagas Sanjaya, Philip Oakley, Philippe Blain,
Philippe Blain
From: Philippe Blain <levraiphilippeblain@gmail.com>
By default, GitHub prefills the PR description using the commit message
for single-commit PRs. This results in a duplicate commit message below
the three-dash line if the contributor does not empty out the PR
description before submitting, which adds noise for reviewers.
Add a note to that effect in MyFirstContribution.txt.
This partly addresses:
https://github.com/gitgitgadget/gitgitgadget/issues/340
Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
Documentation/MyFirstContribution.txt | 10 ++++++++++
1 file changed, 10 insertions(+)
diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index 9eb2dfec959..1da15d9ad44 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -904,6 +904,16 @@ respectively as the subject and body of the cover letter for your change. Refer
to <<cover-letter,"The cover letter">> above for advice on how to title your
submission and what content to include in the description.
+NOTE: For single-patch contributions, your commit message should already be
+meaningful and explain at a high level the purpose (what is happening and why)
+of your patch, so you usually do not need any additional context. In that case,
+remove the PR description that GitHub automatically generates from your commit
+message (your PR description should be empty). If you do need to supply even
+more context, you can do so in that space and it will be appended to the email
+that GitGitGadget will send, between the three-dash line and the diffstat
+(see <<single-patch,Bonus Chapter: One-Patch Changes>> for how this looks once
+submitted).
+
When you're happy, submit your pull request.
[[run-ci-ggg]]
--
gitgitgadget
^ permalink raw reply related [flat|nested] 43+ messages in thread
* Re: [PATCH v3 0/5] Improve MyFirstContribution's GitGitGadget section
2022-05-12 23:43 ` [PATCH v3 " Philippe Blain via GitGitGadget
` (4 preceding siblings ...)
2022-05-12 23:43 ` [PATCH v3 5/5] MyFirstContribution: drop PR description for GGG single-patch contributions Philippe Blain via GitGitGadget
@ 2022-05-19 21:49 ` Junio C Hamano
2022-05-21 16:17 ` Philippe Blain
5 siblings, 1 reply; 43+ messages in thread
From: Junio C Hamano @ 2022-05-19 21:49 UTC (permalink / raw)
To: Philippe Blain via GitGitGadget
Cc: git, Emily Shaffer, Johannes Schindelin, Victoria Dye,
Eric Sunshine, Philippe Blain, Bagas Sanjaya, Philip Oakley
"Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> writes:
> Philippe Blain (5):
> MyFirstContribution: add "Anatomy of a Patch Series" section
> MyFirstContribution: add standalone section on cover letter
> MyFirstContribution: reference "The cover letter" in "Preparing Email"
> MyFirstContribution: reference "The cover letter" in GitGitGadget
> section
> MyFirstContribution: drop PR description for GGG single-patch
> contributions
I am planning to merge it to 'next' soonish. Please speak up if
anybody has any issues.
Thanks.
^ permalink raw reply [flat|nested] 43+ messages in thread
* Re: [PATCH v3 0/5] Improve MyFirstContribution's GitGitGadget section
2022-05-19 21:49 ` [PATCH v3 0/5] Improve MyFirstContribution's GitGitGadget section Junio C Hamano
@ 2022-05-21 16:17 ` Philippe Blain
2022-05-22 1:35 ` Junio C Hamano
0 siblings, 1 reply; 43+ messages in thread
From: Philippe Blain @ 2022-05-21 16:17 UTC (permalink / raw)
To: Junio C Hamano
Cc: git, Emily Shaffer, Johannes Schindelin, Victoria Dye,
Eric Sunshine, Bagas Sanjaya, Philip Oakley
Hi Junio,
Le 2022-05-19 à 17:49, Junio C Hamano a écrit :
> "Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>> Philippe Blain (5):
>> MyFirstContribution: add "Anatomy of a Patch Series" section
>> MyFirstContribution: add standalone section on cover letter
>> MyFirstContribution: reference "The cover letter" in "Preparing Email"
>> MyFirstContribution: reference "The cover letter" in GitGitGadget
>> section
>> MyFirstContribution: drop PR description for GGG single-patch
>> contributions
>
> I am planning to merge it to 'next' soonish. Please speak up if
> anybody has any issues.
>
> Thanks.
>
I just realized that the additional/tweaked content that I added in v3 went into 2/5
where as they should have gone into 1/5 (I'm talking about the changes
*before* the "The cover letter" heading in [1]). I slightly messed up my rebase
it seems, I'm sorry...
Should I send a new version, or is it too late since it's now in 'next' ?
Thanks,
Philippe.
[1] https://github.com/gitgitgadget/git/pull/1226/commits/ee3238f5a9169f0c7d046089c7951791b8db3cab
^ permalink raw reply [flat|nested] 43+ messages in thread
* Re: [PATCH v3 0/5] Improve MyFirstContribution's GitGitGadget section
2022-05-21 16:17 ` Philippe Blain
@ 2022-05-22 1:35 ` Junio C Hamano
2022-05-24 12:29 ` Philippe Blain
0 siblings, 1 reply; 43+ messages in thread
From: Junio C Hamano @ 2022-05-22 1:35 UTC (permalink / raw)
To: Philippe Blain
Cc: git, Emily Shaffer, Johannes Schindelin, Victoria Dye,
Eric Sunshine, Bagas Sanjaya, Philip Oakley
Philippe Blain <levraiphilippeblain@gmail.com> writes:
>>> Philippe Blain (5):
>>> MyFirstContribution: add "Anatomy of a Patch Series" section
>>> MyFirstContribution: add standalone section on cover letter
>>> MyFirstContribution: reference "The cover letter" in "Preparing Email"
>>> MyFirstContribution: reference "The cover letter" in GitGitGadget
>>> section
>>> MyFirstContribution: drop PR description for GGG single-patch
>>> contributions
> I just realized that the additional/tweaked content that I added in v3 went into 2/5
> where as they should have gone into 1/5 (I'm talking about the changes
> *before* the "The cover letter" heading in [1]). I slightly messed up my rebase
> it seems, I'm sorry...
>
> Should I send a new version, or is it too late since it's now in 'next' ?
Thanks for letting me know, and sorry about the confusion.
Could you please send an incremental fix to be queued on top of
these 5 patches?
Thanks.
^ permalink raw reply [flat|nested] 43+ messages in thread
* Re: [PATCH v3 0/5] Improve MyFirstContribution's GitGitGadget section
2022-05-22 1:35 ` Junio C Hamano
@ 2022-05-24 12:29 ` Philippe Blain
2022-05-24 19:06 ` Junio C Hamano
0 siblings, 1 reply; 43+ messages in thread
From: Philippe Blain @ 2022-05-24 12:29 UTC (permalink / raw)
To: Junio C Hamano
Cc: git, Emily Shaffer, Johannes Schindelin, Victoria Dye,
Eric Sunshine, Bagas Sanjaya, Philip Oakley
Hi Junio,
Le 2022-05-21 à 21:35, Junio C Hamano a écrit :
> Philippe Blain <levraiphilippeblain@gmail.com> writes:
>
>>>> Philippe Blain (5):
>>>> MyFirstContribution: add "Anatomy of a Patch Series" section
>>>> MyFirstContribution: add standalone section on cover letter
>>>> MyFirstContribution: reference "The cover letter" in "Preparing Email"
>>>> MyFirstContribution: reference "The cover letter" in GitGitGadget
>>>> section
>>>> MyFirstContribution: drop PR description for GGG single-patch
>>>> contributions
>> I just realized that the additional/tweaked content that I added in v3 went into 2/5
>> where as they should have gone into 1/5 (I'm talking about the changes
>> *before* the "The cover letter" heading in [1]). I slightly messed up my rebase
>> it seems, I'm sorry...
>>
>> Should I send a new version, or is it too late since it's now in 'next' ?
>
> Thanks for letting me know, and sorry about the confusion.
>
> Could you please send an incremental fix to be queued on top of
> these 5 patches?
I can't really send an incremental fix because the final content
as it is in 'next' already is OK; it's just that some content which was added
in patch 2/5 should have been added in 1/5 instead.
It's that too big of a deal, I just wanted to let you know.
Thanks,
Philippe.
^ permalink raw reply [flat|nested] 43+ messages in thread
* Re: [PATCH v3 0/5] Improve MyFirstContribution's GitGitGadget section
2022-05-24 12:29 ` Philippe Blain
@ 2022-05-24 19:06 ` Junio C Hamano
0 siblings, 0 replies; 43+ messages in thread
From: Junio C Hamano @ 2022-05-24 19:06 UTC (permalink / raw)
To: Philippe Blain
Cc: git, Emily Shaffer, Johannes Schindelin, Victoria Dye,
Eric Sunshine, Bagas Sanjaya, Philip Oakley
Philippe Blain <levraiphilippeblain@gmail.com> writes:
> I can't really send an incremental fix because the final content
> as it is in 'next' already is OK; it's just that some content which was added
> in patch 2/5 should have been added in 1/5 instead.
>
> It's that too big of a deal, I just wanted to let you know.
Ah, I mis-read you then.
Such a misdivision may technically break bisectability, but
hopefully nobody bisects the documentation changes and I do not
think we should be worried too much about it.
Thanks.
^ permalink raw reply [flat|nested] 43+ messages in thread