Re: [PATCH v2 1/5] MyFirstContribution: add "Anatomy of a Patch Series" section

[Philippe Blain <levraiphilippeblain@gmail.com>]

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.