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

[Junio C Hamano <gitster@pobox.com>]

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.