git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / mirror / code / Atom feed
From: Junio C Hamano <gitster@pobox.com>
To: Bagas Sanjaya <bagasdotme@gmail.com>
Cc: Philippe Blain via GitGitGadget <gitgitgadget@gmail.com>,
	git@vger.kernel.org, Emily Shaffer <emilyshaffer@google.com>,
	Johannes Schindelin <Johannes.Schindelin@gmx.de>,
	Victoria Dye <vdye@github.com>,
	Eric Sunshine <sunshine@sunshineco.com>,
	Philippe Blain <levraiphilippeblain@gmail.com>
Subject: Re: [PATCH v2 1/5] MyFirstContribution: add "Anatomy of a Patch Series" section
Date: Wed, 11 May 2022 14:30:47 -0700	[thread overview]
Message-ID: <xmqqh75viwoo.fsf@gitster.g> (raw)
In-Reply-To: <YntVo0G8G2mQYCLZ@debian.me> (Bagas Sanjaya's message of "Wed, 11 May 2022 13:20:19 +0700")

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.

  reply	other threads:[~2022-05-11 21:31 UTC|newest]

Thread overview: 43+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-04-27 19:04 [PATCH 0/3] Improve MyFirstContribution's GitGitGadget section Philippe Blain via GitGitGadget
2022-04-27 19:04 ` [PATCH 1/3] MyFirstContribution: move cover letter description to a separate file Philippe Blain via GitGitGadget
2022-04-27 21:15   ` Eric Sunshine
2022-04-27 22:02     ` Philippe Blain
2022-04-27 21:48   ` Junio C Hamano
2022-04-28 18:16     ` Philippe Blain
2022-04-27 19:04 ` [PATCH 2/3] MyFirstContribution: also explain cover letter in GitGitGadget section Philippe Blain via GitGitGadget
2022-04-27 20:43   ` Victoria Dye
2022-04-28 18:21     ` Philippe Blain
2022-04-29 16:27       ` Victoria Dye
2022-05-10 23:45         ` Philippe Blain
2022-04-27 19:04 ` [PATCH 3/3] MyFirstContribution: drop PR description for GGG single-patch contributions Philippe Blain via GitGitGadget
2022-04-27 21:56   ` Junio C Hamano
2022-04-28 18:25     ` Philippe Blain
2022-04-28 19:43       ` Junio C Hamano
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  6:20     ` Bagas Sanjaya
2022-05-11 21:30       ` Junio C Hamano [this message]
2022-05-11 21:48         ` Philippe Blain
2022-05-11 22:09           ` Junio C Hamano
2022-05-12 23:00             ` Philippe Blain
2022-05-12 12:11     ` Philip Oakley
2022-05-12 22:53       ` Philippe Blain
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
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   ` [PATCH v2 4/5] MyFirstContribution: reference "The cover letter" in GitGitGadget section 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
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
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     ` [PATCH v3 3/5] MyFirstContribution: reference "The cover letter" in "Preparing Email" 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
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
2022-05-21 16:17       ` Philippe Blain
2022-05-22  1:35         ` Junio C Hamano
2022-05-24 12:29           ` Philippe Blain
2022-05-24 19:06             ` Junio C Hamano

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=xmqqh75viwoo.fsf@gitster.g \
    --to=gitster@pobox.com \
    --cc=Johannes.Schindelin@gmx.de \
    --cc=bagasdotme@gmail.com \
    --cc=emilyshaffer@google.com \
    --cc=git@vger.kernel.org \
    --cc=gitgitgadget@gmail.com \
    --cc=levraiphilippeblain@gmail.com \
    --cc=sunshine@sunshineco.com \
    --cc=vdye@github.com \
    --subject='Re: [PATCH v2 1/5] MyFirstContribution: add "Anatomy of a Patch Series" section' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Code repositories for project(s) associated with this inbox:

	https://80x24.org/mirrors/git.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).