Re: [PATCH v3 1/3] MyFirstContribution: recommend shallow threading of cover letters

From: Karthik Nayak <karthik.188@gmail.com>
Date: Jun 10, 2026, 11:08 UTC
Message-ID: <CAOLa=ZQE-kkpSX=pP2A6SXdbp_O6AHzRmbUDOtKCsvz2Yz66Ng@mail.gmail.com>
In-Reply-To: <20260608-pks-b4-v3-1-f5e497d10c56@pks.im>

Patrick Steinhardt <ps@pks.im> writes:

Show 11 quoted lines

> The "MyFirstContribution" document recommends the use of deep threading
> of cover letters: every cover letter of subsequent iterations shall be
> linked to the cover letter of the preceding version. The result of this
> is that eventually, threads with many versions are getting nested so
> deep that it becomes hard to follow.
>
> Adapt the recommendation to instead propose shallow threading of cover
> letters: instead of linking the cover letter to the previous cover
> letter, the user is supposed to always link it to the first cover
> letter. This still makes it easy to follow the iterations, but has the
> benefit of nesting to a much shallower level.

Should we also modify 'Documentation/SubmittingPatches'? Which states:

  All subsequent versions of a patch series and other related patches
  should be grouped into their own e-mail thread to help readers find
  all parts of the series.  To that end, send them as replies to either
  an additional "cover letter" message (see below), the first patch, or
  the respective preceding patch. Here is a
  link:MyFirstContribution.html#v2-git-send-email[step-by-step guide] on
  how to submit updated versions of a patch series.

Personally, I find it a bit awkward when new versions are sent as a new separate thread, especially when the subject is changed over versions.

Show 42 quoted lines

>
> Signed-off-by: Patrick Steinhardt <ps@pks.im>
> ---
>  Documentation/MyFirstContribution.adoc | 8 ++++----
>  1 file changed, 4 insertions(+), 4 deletions(-)
>
> diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc
> index b9fdefce02..984b7f5aa8 100644
> --- a/Documentation/MyFirstContribution.adoc
> +++ b/Documentation/MyFirstContribution.adoc
> @@ -790,7 +790,7 @@ We can note a few things:
>    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).
> +  first 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,
> @@ -1214,7 +1214,7 @@ between your last version and now, if it's something significant. You do not
>  need the exact same body in your second cover letter; focus on explaining to
>  reviewers the changes you've made that may not be as visible.
>
> -You will also need to go and find the Message-ID of your previous cover letter.
> +You will also need to go and find the Message-ID of your first cover letter.
>  You can either note it when you send the first series, from the output of `git
>  send-email`, or you can look it up on the
>  https://lore.kernel.org/git[mailing list]. Find your cover letter in the
> @@ -1227,8 +1227,8 @@ Message-ID: <foo.12345.author@example.com>
>
>  Your Message-ID is `<foo.12345.author@example.com>`. This example will be used
>  below as well; make sure to replace it with the correct Message-ID for your
> -**previous cover letter** - that is, if you're sending v2, use the Message-ID
> -from v1; if you're sending v3, use the Message-ID from v2.
> +**first cover letter** - that is, for any subsequent version that you send,
> +always use the Message-ID from v1.
>
>  While you're looking at the email, you should also note who is CC'd, as it's
>  common practice in the mailing list to keep all CCs on a thread. You can add
>
> --
> 2.54.0.1136.gdb2ca164c4.dirty

The patch looks good.