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

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

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.