We're about to extend our documentation to recommend b4 for sending patch series ot the mailing list. Prepare for this by introducing a b4 configuration so that the tool knows to honor our preferences. For now, this configuration does two things:

  - It configures "send-same-thread = shallow", which tells b4 to always
    send subsequent versions of the same patch series as a reply to the
    cover letter of the first version.

  - It configures "prep-cover-template", which tells b4 to use a custom
    template for the cover letter. The most important change compared to
    the default template is that our custom template also includes a
    range-diff.

There's potentially more things that we may want to configure going forward, like for example auto-configuration of folks to Cc on certain patches. But these two tweaks feel like a good place to start.

Signed-off-by: Patrick Steinhardt <ps@pks.im>
---
 .b4-config         |  3 +++
 .b4-cover-template | 11 +++++++++++
 2 files changed, 14 insertions(+)

Hi,

this small patch series wires up b4 in Git and recommends the use thereof via "MyFirstContribution", as discussed in [1].

Thanks!

Patrick

[1]: <xmqqik81xpqx.fsf@gitster.g>

---
Patrick Steinhardt (2):
      b4: introduce configuration for the Git project
      Documentation/MyFirstContribution: recommend the use of b4

 .b4-config                             |  3 ++
 .b4-cover-template                     | 11 +++++
 Documentation/MyFirstContribution.adoc | 81 ++++++++++++++++++++++++++++++++--
 Documentation/SubmittingPatches        |  6 ++-
 4 files changed, 96 insertions(+), 5 deletions(-)

--- base-commit: 9ac3f193c05c2237e2b14ebaa1149e9fc8a1abe0 change-id: 20260602-pks-b4-31cc20d7f84b

The b4 tool originates from the Linux kernel community and is intended to help mailing-list based workflows. It automates a lot of the annoying bookkeeping tasks that contributors typically need to do: tracking the list of recipients, Message-IDs, range-diffs and the like. In addition to that, b4 also has many other subcommands that help the maintainer and reviewers.

The Git project uses the same infrastructure as the kernel, so this tool is also a very good fit for us. Adapt "MyFirstContribution" to explicitly recommend its use.

Signed-off-by: Patrick Steinhardt <ps@pks.im>
---
 Documentation/MyFirstContribution.adoc | 81 ++++++++++++++++++++++++++++++++--
 Documentation/SubmittingPatches        |  6 ++-
 2 files changed, 82 insertions(+), 5 deletions(-)

Patrick Steinhardt <ps@pks.im> writes:

Shipping a sample like ".b4-config.sample" that users who opt-in can copy-and-edit into the final name ".b4-config" is OK, but I'd rather not to ship the configuration files that the users would want to edit (hence making the tree dirty).

On Tue, Jun 02, 2026 at 10:32:23PM +0900, Junio C Hamano wrote:

I think shipping this as-is makes sense though, as it allows us to make b4 behave the way we want it to without the user having to do anything. If users actually want to reconfigure those values they can by saying `git config set b4.<foobar>`, as the repository-local configuration will override whatever `.b4-config` has.

Patrick

Hi Patrick and Junio,

Just so happens that I just submitted my first patch. At this point, I may or should be the target audience for this document.

I personally watched Patrick's videos with Scott Chacon[1] first, and I reviewed them many times until I could do those "manual" git operations.

So for statement like this and with my personal experience, I would say b4 is a more suitable option for senior contributors, as they already know, for example, what Message-ID and range-diffs are. But apparently, whose who use forges may not know.

Back to the patch, I think regarding b4 as a more advanced contribution way for those who had contributed via mailing lists for more than one time is a better expression or formulation. Here I mean "b4 prep", other usage like "b4 mbox" and "b4 am" are of course more basic, and be mentioned as tips when interacting with Git mailing list.

A bit too wordy, in conclusion: Suggest that new contributors master classic git operations first. When they are familiar with those process, b4 might be a good option.

Thanks! -- [1] https://www.youtube.com/watch?v=mjYac9SwIK0&t=1s (Part 1)

On 02/06/2026 2:32 pm, Junio C Hamano wrote:

Hmm, for those of us not in the know, perhaps mention the b4 documentation at 'b4.docs.kernel.org' (which includes how to install b4 ... ;) ).

ATB, Ramsay Jones

Patrick Steinhardt <ps@pks.im> wrote:

s/ot/to/

Huh?  Doesn't MyFirstContribution speak *against* shallow threading?

	        [...]  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.

Besides, GitGitGadget also employs that kind of nested threading, if I'm not mistaken.

Thanks.

On Tue, Jun 02, 2026 at 08:09:55PM +0300, Tuomas Ahola wrote:

I don't get it. Doesn't shallow threading means every following patches are replying to the cover letter? Replying to the previous one is --chain-reply-to, if I'm not mistaken.

Thanks.

Ramsay Jones <ramsay@ramsayjones.plus.com> writes:

Thanks for raising an excellent point.

On Wed, Jun 03, 2026 at 11:59:48AM +0900, Junio C Hamano wrote:

I already refer to the docs in the second commit. Let me maybe reorder them so that we first show how it's used before tweaking it.

Patrick

On Wed, Jun 03, 2026 at 12:09:16AM +0800, Weijie Yuan wrote:

I think it's perfectly suitable for newcomers, too. It automates so many of the concepts that a contributor has to learn way less about mailing list specific concepts, which reduces the learning curve.

Ah, that's what you're hinting at. So you mean to say that folks should first understand the basics before basically automating all of the parts for them?

I guess I can see where you're coming from, but I'm not sure I agree with this a 100%. My main goal is to make it easier for new community members to contribute to Git, and that means that we should automate all the hard parts as far as possible. This saves those new contributors from frustration, and it means that reviewers on the mailing list won't have to teach every single new contributor about how they should thread the mails, generate range-diffs and the like.

So in the end, it saves both their and our time, but the learning opportunity is of course a bit diminished. I'd gladly accept that tradeoff though.

Thanks for your input!

Patrick

On Wed, Jun 03, 2026 at 10:12:22AM +0800, Weijie Yuan wrote:

Shallow threading basically means that all patches are sent as a response to the current cover letter, and the current cover letter is always attached to the cover letter of the _first_ version.

So this quote is definitely at odds with the configuration I have proposed. It's actually quite surprising to me that we recommend deep threading -- I personally find it extremely hard to navigate as the nesting eventually gets way too deep.

You know -- I'll include a patch that changes the wording there to also use shallow nesting, mostly to kick off a discussion and arrive at a decision there.

Thanks!

Patrick

Hi,

this small patch series wires up b4 in Git and recommends the use thereof via "MyFirstContribution", as discussed in [1].

Changes in v2:
  - Reorder commits so that the b4 docs are added first.
  - Add a section that highlights how to configure b4, and that points
    out that the per-project defaults can be overridden via Git
    configuration.
  - Add a patch to MyFirstContribution that recommends shallow
    threading. I mostly intend this to be a discussion starter so that
    the `.b4-config` file matches our preferred threading style.
  - Fix a typo.
  - Link to v1: https://patch.msgid.link/20260602-pks-b4-v1-0-a7ae5a49e9cf@pks.im

Thanks!

Patrick

[1]: <xmqqik81xpqx.fsf@gitster.g>

---
Patrick Steinhardt (3):
      Documentation/MyFirstContribution: recommend shallow threading
      Documentation/MyFirstContribution: recommend the use of b4
      b4: introduce configuration for the Git project

 .b4-config                             |  6 +++
 .b4-cover-template                     | 11 ++++
 Documentation/MyFirstContribution.adoc | 96 ++++++++++++++++++++++++++++++++--
 Documentation/SubmittingPatches        |  6 ++-
 4 files changed, 112 insertions(+), 7 deletions(-)

Range-diff versus v1:

-:  ---------- > 1:  359ce9ec24 Documentation/MyFirstContribution: recommend shallow threading
2:  55fffeb8f8 ! 2:  ce9aa56846 Documentation/MyFirstContribution: recommend the use of b4
    @@ Documentation/MyFirstContribution.adoc: index 88f126184c..38da593a60 100644
     +version. `b4` automatically bumps the version to `v2`, generates the range-diff
     +against the previous iteration, and threads the new series as a reply to the
     +cover letter of the first version.
    ++
    ++[[configure-b4]]
    ++=== Configure b4
    ++
    ++`b4` can be configured via linkgit:git-config[1]. In addition to that, projects
    ++can have their own set of defaults in `.b4-config` in the root tree, which also
    ++uses Git's config format. The user's configuration always takes precedence over
    ++the per-project defaults.
    ++
    ++Refer to the https://b4.docs.kernel.org/en/latest/config.html[b4 config documentation]
    ++for more information on the available options.
     +
      [[now-what]]
      == My Patch Got Emailed - Now What?
1:  0fe6cf8511 ! 3:  e2bf7b6e46 b4: introduce configuration for the Git project
    @@ Commit message
         b4: introduce configuration for the Git project
     
         We're about to extend our documentation to recommend b4 for sending
    -    patch series ot the mailing list. Prepare for this by introducing a b4
    +    patch series to the mailing list. Prepare for this by introducing a b4
         configuration so that the tool knows to honor our preferences. For now,
         this configuration does two things:
     
    @@ Commit message
         forward, like for example auto-configuration of folks to Cc on certain
         patches. But these two tweaks feel like a good place to start.
     
    +    Note that these values only serve as defaults, and users may want to
    +    tweak those defaults based on their own preference. Luckily, users can
    +    do that without having to touch `.b4-config` at all, as b4 allows them
    +    to override values via Git configuration:
    +
    +        ```
    +        $ git config set b4.prep-cover-template /does/not/exist
    +        $ b4 send --dry-run
    +        ERROR: prep-cover-template says to use x, but it does not exist
    +        ```
    +
    +    So this gives users an easy way to override our defaults without having
    +    to touch ".b4-config", which would dirty the tree.
    +
         Signed-off-by: Patrick Steinhardt <ps@pks.im>
     
      ## .b4-config (new) ##
     @@
    ++# Note that these are default values that you can tweak via the typical
    ++# git-config(1) machinery. You thus shouldn't ever have to change this file.
    ++# See also https://b4.docs.kernel.org/en/latest/config.html.
     +[b4]
     +send-same-thread = shallow
     +prep-cover-template = ./.b4-cover-template

--- base-commit: 9ac3f193c05c2237e2b14ebaa1149e9fc8a1abe0 change-id: 20260602-pks-b4-31cc20d7f84b

The "MyFirstContribution" document recommends the use of deep threading: 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: 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.

Signed-off-by: Patrick Steinhardt <ps@pks.im>
---
 Documentation/MyFirstContribution.adoc | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

The b4 tool originates from the Linux kernel community and is intended to help mailing-list based workflows. It automates a lot of the annoying bookkeeping tasks that contributors typically need to do: tracking the list of recipients, Message-IDs, range-diffs and the like. In addition to that, b4 also has many other subcommands that help the maintainer and reviewers.

The Git project uses the same infrastructure as the kernel, so this tool is also a very good fit for us. Adapt "MyFirstContribution" to explicitly recommend its use.

Signed-off-by: Patrick Steinhardt <ps@pks.im>
---
 Documentation/MyFirstContribution.adoc | 92 ++++++++++++++++++++++++++++++++--
 Documentation/SubmittingPatches        |  6 ++-
 2 files changed, 93 insertions(+), 5 deletions(-)

We're about to extend our documentation to recommend b4 for sending patch series to the mailing list. Prepare for this by introducing a b4 configuration so that the tool knows to honor our preferences. For now, this configuration does two things:

  - It configures "send-same-thread = shallow", which tells b4 to always
    send subsequent versions of the same patch series as a reply to the
    cover letter of the first version.

  - It configures "prep-cover-template", which tells b4 to use a custom
    template for the cover letter. The most important change compared to
    the default template is that our custom template also includes a
    range-diff.

There's potentially more things that we may want to configure going forward, like for example auto-configuration of folks to Cc on certain patches. But these two tweaks feel like a good place to start.

Note that these values only serve as defaults, and users may want to tweak those defaults based on their own preference. Luckily, users can do that without having to touch `.b4-config` at all, as b4 allows them to override values via Git configuration:

    ```
    $ git config set b4.prep-cover-template /does/not/exist
    $ b4 send --dry-run
    ERROR: prep-cover-template says to use x, but it does not exist
    ```

So this gives users an easy way to override our defaults without having to touch ".b4-config", which would dirty the tree.

Signed-off-by: Patrick Steinhardt <ps@pks.im>
---
 .b4-config         |  6 ++++++
 .b4-cover-template | 11 +++++++++++
 2 files changed, 17 insertions(+)

On Wed, Jun 03, 2026 at 08:55:04AM +0200, Patrick Steinhardt wrote:

Sorry I'm a little confused. The example thread at git-scm.com:

https://git-scm.com/docs/MyFirstContribution#ready-to-share

Isn't this actually supporting shallow nesting?

In my understanding, deep threading == --chain-reply-to, so can you point out where do Git recommend deep threading? I always thought Git supports shallow threading.

Thanks! And please forgive me if I am wrong :-)

On Wed, Jun 03, 2026 at 08:54:56AM +0200, Patrick Steinhardt wrote:

Yeah, after I expressed my opinion, I also felt a bit conflicted though. So I also agree with your intension.

Make an inappropriate metaphor: some usage of b4 and magit are "Porcelain" to Git. Whether how you are good at using those porcelains like magit or lazygit, in the end, you will eventually have to face git cli one day.

So the same for b4. If we list these three methods equally and simultaneously, the logic might be not that correct.

Your proposal:

           contribution workflow
                    |
    -------------------------------------
    |                 |                 |
    v                 v                 v
GitGitGadget   traditional email        b4
```

But I would frame it more like this:

           contribution workflow
                    |
        -------------------------
        |                       |
        v                       v
 GitGitGadget        traditional email workflow
                                      \
                                       \
                                       b4

For exmaple, If I am at this page the fisrt time:
    https://git-scm.com/docs/MyFirstContribution
And, I see these 3 ways, okay, I choose b4.

After installing b4 and reading some manuals, I would wonder: what's cover letter? what's Message-ID? So after a while, I would still have to learn those stuff and how b4 indeed optimize those complicated process.

So, to put it another way.. b4 is developed for high-level maintainers, who are apparently familiar with traditional ways. Therefore b4 saves their time. But for some beginers like me, I still have to know those concepts first.

But yeah, there are definitely some people would happily accept b4 and contribute easily. Thus, I agree this tradeoff.

-- Sent before reading v2, hope there's no conflict :-)

That said, my ideas may be too nitpicking. Overall, I do think that introducing b4 support would be a good thing.

Thanks for the replies, and for bearing with my questions/comments.

Weijie Yuan

On Wed, Jun 03, 2026 at 03:51:21PM +0800, Weijie Yuan wrote:

Ah, I know you mean the deep nesting of cover letters, sorry, now I know.

Thanks!

Patrick Steinhardt <ps@pks.im> wrote:

If we adapt this change to the guidance, let's fix also other places of the document that talk about replying to the previous cover letter.

-----8<-----

I'm afraid there will be some chaos.

As mentioned earlier, GitGitGadget now supports deep nesting of iterations, if b4 changes while GitGitGadget doesn't, it would be inconsistent in the archive. So, negotiation is necessary here.

As I know, b4 can generate a cover letter containing "Changes with vn", e.g. in [PATCH v5 00/10], there would be Changes with v4, v3, v2, v1. In this case, it is semantically correct that the cover letter of v5 is replying-to the cover letter of v1.

But in traditional way, it seems that the norm is put a range-diff in the cover letter. In this case, chain-reply-to makes more sence to me: e.g. The cover letter contains the range-diff against v2, so cover letter v3 is pointing to cover letter v2. (I don't know whether git format-patch accepts several --range-diff or not, but if so, I guess it might be painful to typing several refs, or copy and paste from previous cover letter) Therefore, if git format-patch could generate cover letter containing all the changes with v4/v3/v2/v1 as b4 does, it would be consistent, and semantically correct to pointing to the first cover letter.

Do we need to consider backward compatibility here? ;-)

Thanks!

On Wed, Jun 03, 2026 at 08:55:04AM +0200, Patrick Steinhardt wrote:

No, in Git shallow threading means that all patches are sent as a respose to the current cover letter, period. It has nothing to do with whether the current cover letter is sent as a reply to the cover letter of the first or the previous version.

Deep threading means that every mail is a reply to the previous one. Again, it has nothing to do with the relation of the current cover letter and the previous cover letters.

Therefore, we do not recommend deep threading.

On Wed, Jun 03, 2026 at 01:07:33PM +0200, SZEDER Gábor wrote:

Thanks, agree

So the same reason with Patrick?

Thanks

SZEDER Gábor <szeder.dev@gmail.com> wrote:

That seems to be the established meaning of shallow threading, e.g. in `git format-patch --thread=shallow`. Unfortunately there is a slight terminology clash here.

Indeed, in B4 the config option `b4.send-same-thread = shallow` *is* about whether the cover letter is a reply to v1 or v(n-1).

In the usual meaning of the word that is the case. Most certainly we don't recommend that kind of deep threading, but that wasn't the question we were discussing here.

Patrick Steinhardt <ps@pks.im> writes:

Is it worth to note this requires v0.15 or higher?

That version was released only 2 months ago, I can imagine many distros still ship an older version, what happens if a version doesn't support this setting yet?

On Wed, Jun 3, 2026, at 08:58, Patrick Steinhardt wrote:

Only today did I notice that your eleven-version git-history(1) series uses this style. (Or: today I noticed that it’a thing)

https://lore.kernel.org/git/20250819-b4-pks-history-builtin-v1-0-9b77c32688fe@pks.im/

That would have had a bad rightward drift with the usual reply to previous version style.

I’ve been reading Lore on Safari on mobile and some threads go so deep that the replies just become unclickable backticks. *Huh?* Well I can use the Next/Previous buttons and maybe there is a way to make it work, but I’ve just given up on those right-going subthreads. ;)

... and I also don’t see any drawbacks to that threading, using that series as an example. It looks just as comprehensible as the usual style.

SZEDER Gábor <szeder.dev@gmail.com> writes:

The above exactly matches my understanding of the current best practice. Inside an iteration of a series, we want a cover letter with everybody else responding to it. We do not have a word to describe how the latest iteration refers to its previous iteration via In-reply-to: or References: headers, but our preference is to make the cover letter of iteration N+1 to be a response to the cover letter of iteration N.

For a single-patch topic (without a cover letter) with multiple iterations, each iteration would be response to its previous iteration, which may make it look like "deep threading", but as you pointed out, the "deep threading" concept does not go across iterations.

Having said that, I've seen a cover letter of iteration N (for any value of N > 1) that respondes to the cover letter of the initial iteration. While it seems not to break "br" and the lore archive does not seem unhappy about it, I am not sure if tooling used by other people are also happy with it.

Thanks.

Patrick Steinhardt <ps@pks.im> writes:

The GitGitGadget method includes Running CI, maybe that's worth mentioning the user is responsible themselves to run the whole test suite? Or is this outside the scope of this series, since `git send-email` doesn't include that too.

On Wed, Jun 03, 2026 at 01:01:45PM +0300, Tuomas Ahola wrote:

Good catch, thanks!

Patrick

On Wed, Jun 03, 2026 at 06:29:32PM +0800, Weijie Yuan wrote:

I think "chaos" is a bit exaggerated. We already have both styles on the mailing list, and I think in general people are able to cope with that just fine. :)

That's a good point though -- if we change the recommendation, we should aim to change it consistently. I'll talk with Dscho (maintainer of GGG) today.

Thanks!

Patrick

On Wed, Jun 03, 2026 at 10:09:39PM +0200, Kristoffer Haugsbakk wrote:

Yeah. It doesn't matter much for patch series that don't require many iterations. But eventually I feel like it gets out-of-hand to have the deep nesting.

Patrick

On Thu, Jun 04, 2026 at 07:25:37AM +0200, Toon Claes wrote:

I'd say it's out-of-scope for this patch series.

That being said, I have been wondering last week whether we can automate running CI in some fashion to shorten feedback cycles, bridge the gap between the mailing list and CI and ultimately help both reviewers and Junio. Some subsystems in the Linux kernel for example have tooling that picks up patch series from the mailing list, runs it through CI and then reports results to the mailing list (for example [1]).

Having something like that might be valuable for us, too.

Patrick

[1]: https://github.com/linux-netdev/nipa

On Wed, Jun 03, 2026 at 01:07:33PM +0200, SZEDER Gábor wrote:

Oh, you're right of course. I totally forgot that we even had this style.

Patrick

On Thu, Jun 04, 2026 at 10:11:37AM +0900, Junio C Hamano wrote:

Yeah, I always use that style myself. I mostly prefer it because the nesting for long-running patch series with many versions is eventually getting out of hand and hard to navigate, and I haven't seen any tooling breaking as a result of that style.

If I'm the only one who thinks that style to be preferable I am happy to adapt. I'm not really sure yet what the consensus is -- I'll send one more version that includes the changes, but if we continue to be split or in favor of the current status quo I'll drop those in the next version.

Thanks!

Patrick

On Wed, Jun 03, 2026 at 03:58:38PM +0200, Toon Claes wrote:

That's fair. In case it's not supported we fall back to the default, which is to not use threading at all.

Might be another indicator that we should just stick with the current threading style.

Patrick

Hi,

this small patch series wires up b4 in Git and recommends the use thereof via "MyFirstContribution", as discussed in [1].

Changes in v3:
  - I wasn't really able to judge consensus one way or the other
    regarding the deep vs shallow nesting of cover letters, so I still
    have the change to shallow nesting of cover letters part of this
    series. If we continue to be split on this one (or if we favor the
    current status quo) I'm happy to drop the first patch and adapt the
    last patch to use deep nesting of cover letters instead.
  - Hopefully fix some confusion by saying "shallow/deep threading of
    cover letters".
  - Fix some more instances where we recommend deep threading of cover
    letters.
  - Link to v2: https://patch.msgid.link/20260603-pks-b4-v2-0-a8aea0aa2c23@pks.im

Changes in v2:
  - Reorder commits so that the b4 docs are added first.
  - Add a section that highlights how to configure b4, and that points
    out that the per-project defaults can be overridden via Git
    configuration.
  - Add a patch to MyFirstContribution that recommends shallow
    threading. I mostly intend this to be a discussion starter so that
    the `.b4-config` file matches our preferred threading style.
  - Fix a typo.
  - Link to v1: https://patch.msgid.link/20260602-pks-b4-v1-0-a7ae5a49e9cf@pks.im

Thanks!

Patrick

[1]: <xmqqik81xpqx.fsf@gitster.g>

---
Patrick Steinhardt (3):
      MyFirstContribution: recommend shallow threading of cover letters
      MyFirstContribution: recommend the use of b4
      b4: introduce configuration for the Git project

 .b4-config                             |   6 ++
 .b4-cover-template                     |  11 ++++
 Documentation/MyFirstContribution.adoc | 100 ++++++++++++++++++++++++++++++---
 Documentation/SubmittingPatches        |   6 +-
 4 files changed, 114 insertions(+), 9 deletions(-)

Range-diff versus v2:

1:  f7784c8f7f ! 1:  4b0c4f9aca Documentation/MyFirstContribution: recommend shallow threading
    @@ Metadata
     Author: Patrick Steinhardt <ps@pks.im>
     
      ## Commit message ##
    -    Documentation/MyFirstContribution: recommend shallow threading
    +    MyFirstContribution: recommend shallow threading of cover letters
     
    -    The "MyFirstContribution" document recommends the use of deep threading:
    -    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.
    +    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: 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.
    +    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.
     
         Signed-off-by: Patrick Steinhardt <ps@pks.im>
     
      ## Documentation/MyFirstContribution.adoc ##
    +@@ Documentation/MyFirstContribution.adoc: 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,
    +@@ Documentation/MyFirstContribution.adoc: 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
     @@ Documentation/MyFirstContribution.adoc: Message-ID: <foo.12345.author@example.com>
      
      Your Message-ID is `<foo.12345.author@example.com>`. This example will be used
2:  e8f3caf73a ! 2:  625de75a33 Documentation/MyFirstContribution: recommend the use of b4
    @@ Metadata
     Author: Patrick Steinhardt <ps@pks.im>
     
      ## Commit message ##
    -    Documentation/MyFirstContribution: recommend the use of b4
    +    MyFirstContribution: recommend the use of b4
     
         The b4 tool originates from the Linux kernel community and is intended
         to help mailing-list based workflows. It automates a lot of the annoying
3:  35591c55c8 = 3:  a95973cfb6 b4: introduce configuration for the Git project

--- base-commit: 9ac3f193c05c2237e2b14ebaa1149e9fc8a1abe0 change-id: 20260602-pks-b4-31cc20d7f84b

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.

Signed-off-by: Patrick Steinhardt <ps@pks.im>
---
 Documentation/MyFirstContribution.adoc | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

The b4 tool originates from the Linux kernel community and is intended to help mailing-list based workflows. It automates a lot of the annoying bookkeeping tasks that contributors typically need to do: tracking the list of recipients, Message-IDs, range-diffs and the like. In addition to that, b4 also has many other subcommands that help the maintainer and reviewers.

The Git project uses the same infrastructure as the kernel, so this tool is also a very good fit for us. Adapt "MyFirstContribution" to explicitly recommend its use.

Signed-off-by: Patrick Steinhardt <ps@pks.im>
---
 Documentation/MyFirstContribution.adoc | 92 ++++++++++++++++++++++++++++++++--
 Documentation/SubmittingPatches        |  6 ++-
 2 files changed, 93 insertions(+), 5 deletions(-)

We're about to extend our documentation to recommend b4 for sending patch series to the mailing list. Prepare for this by introducing a b4 configuration so that the tool knows to honor our preferences. For now, this configuration does two things:

  - It configures "send-same-thread = shallow", which tells b4 to always
    send subsequent versions of the same patch series as a reply to the
    cover letter of the first version.

  - It configures "prep-cover-template", which tells b4 to use a custom
    template for the cover letter. The most important change compared to
    the default template is that our custom template also includes a
    range-diff.

There's potentially more things that we may want to configure going forward, like for example auto-configuration of folks to Cc on certain patches. But these two tweaks feel like a good place to start.

Note that these values only serve as defaults, and users may want to tweak those defaults based on their own preference. Luckily, users can do that without having to touch `.b4-config` at all, as b4 allows them to override values via Git configuration:

    ```
    $ git config set b4.prep-cover-template /does/not/exist
    $ b4 send --dry-run
    ERROR: prep-cover-template says to use x, but it does not exist
    ```

So this gives users an easy way to override our defaults without having to touch ".b4-config", which would dirty the tree.

Signed-off-by: Patrick Steinhardt <ps@pks.im>
---
 .b4-config         |  6 ++++++
 .b4-cover-template | 11 +++++++++++
 2 files changed, 17 insertions(+)

On Mon, Jun 08, 2026 at 08:48:27AM +0200, Patrick Steinhardt wrote:

Oops, sorry for my poor English, I guess "messy" would be a more proper choice here? ;-)

Thanks for your effort on this! Let´s see if the community can get on the same page about this.

Thanks!

Patrick Steinhardt <ps@pks.im> writes:

Personally I don't care too much. I'm used to the shallow threading, so I'm fine with that.

Now on the other hand, looking at a few examples I see GitGitGadget does deep nesting. Wouldn't it make sense to be consistent?

Anyhow, I don't think it's worth it to keep bike shedding about this. In all methods we recommend to Cc people, I think that's more important then caring about how messages are threaded (for example, I've noticed LKML doesn't thread at all, i.e. `b4.send-same-thread=no` which is the default).

Bottom line, for me this series is good to go in.

Toon Claes <toon@iotcl.com> writes:

Good point to stress about whom to involve.

As long as it does not hurt automation, I do not care too much, but that default is somewhat surprising to me. The setting actively discourages tools from finding previous iterations.

Yeah, sounds good to me.

On Tue, Jun 09, 2026 at 02:04:15PM +0200, Toon Claes wrote:

I've chatted with Dscho about this, and he mentioned that Stolee has already opened [1]. So yes, if we agree to change the recommendation we should also adapt GGG.

Patrick

[1]: https://github.com/gitgitgadget/gitgitgadget/issues/2254

Patrick Steinhardt <ps@pks.im> writes:

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.

The patch looks good.

Patrick Steinhardt <ps@pks.im> writes:

Nit: This is in the past now

This looks similar to what I have locally too, happy to see this land.

On Wed, Jun 10, 2026 at 07:08:33AM -0400, Karthik Nayak wrote:

I don't necessarily see this as contradicting advice, I rather read it as "patches of vN+1 should have their own subthread". But it certainly is confusingly written, and I'm not even sure myself whether I'm reading it correctly or not.

I kind of feel like this is a bit outside the scope of this series. Also because I'm not a 100% sure how to reword this to make it read nicer :) But I'm very happy to accept suggestions here.

Patrick

On Wed, Jun 10, 2026 at 07:13:33AM -0400, Karthik Nayak wrote:

True, will fix.

Patrick

Hi,

this small patch series wires up b4 in Git and recommends the use thereof via "MyFirstContribution", as discussed in [1].

Changes in v4:
  - Improve a commit message.
  - Link to v3: https://patch.msgid.link/20260608-pks-b4-v3-0-f5e497d10c56@pks.im

Changes in v3:
  - I wasn't really able to judge consensus one way or the other
    regarding the deep vs shallow nesting of cover letters, so I still
    have the change to shallow nesting of cover letters part of this
    series. If we continue to be split on this one (or if we favor the
    current status quo) I'm happy to drop the first patch and adapt the
    last patch to use deep nesting of cover letters instead.
  - Hopefully fix some confusion by saying "shallow/deep threading of
    cover letters".
  - Fix some more instances where we recommend deep threading of cover
    letters.
  - Link to v2: https://patch.msgid.link/20260603-pks-b4-v2-0-a8aea0aa2c23@pks.im

Changes in v2:
  - Reorder commits so that the b4 docs are added first.
  - Add a section that highlights how to configure b4, and that points
    out that the per-project defaults can be overridden via Git
    configuration.
  - Add a patch to MyFirstContribution that recommends shallow
    threading. I mostly intend this to be a discussion starter so that
    the `.b4-config` file matches our preferred threading style.
  - Fix a typo.
  - Link to v1: https://patch.msgid.link/20260602-pks-b4-v1-0-a7ae5a49e9cf@pks.im

Thanks!

Patrick

[1]: <xmqqik81xpqx.fsf@gitster.g>

---
Patrick Steinhardt (3):
      MyFirstContribution: recommend shallow threading of cover letters
      MyFirstContribution: recommend the use of b4
      b4: introduce configuration for the Git project

 .b4-config                             |   6 ++
 .b4-cover-template                     |  11 ++++
 Documentation/MyFirstContribution.adoc | 100 ++++++++++++++++++++++++++++++---
 Documentation/SubmittingPatches        |   6 +-
 4 files changed, 114 insertions(+), 9 deletions(-)

Range-diff versus v3:

1:  1aec56f76c = 1:  b6b488e6a8 MyFirstContribution: recommend shallow threading of cover letters
2:  f2036769bd = 2:  1a68b993d2 MyFirstContribution: recommend the use of b4
3:  fb522c7d90 ! 3:  5bc8fba96a b4: introduce configuration for the Git project
    @@ Metadata
      ## Commit message ##
         b4: introduce configuration for the Git project
     
    -    We're about to extend our documentation to recommend b4 for sending
    -    patch series to the mailing list. Prepare for this by introducing a b4
    -    configuration so that the tool knows to honor our preferences. For now,
    -    this configuration does two things:
    +    In the preceding commit we have extended our documentation to recommend
    +    b4 for sending patch series to the mailing list. Introduce configuration
    +    so that it knows to honor preferences of the Git project by default. For
    +    now, this configuration does two things:
     
           - It configures "send-same-thread = shallow", which tells b4 to always
             send subsequent versions of the same patch series as a reply to the

--- base-commit: 9ac3f193c05c2237e2b14ebaa1149e9fc8a1abe0 change-id: 20260602-pks-b4-31cc20d7f84b

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.

Signed-off-by: Patrick Steinhardt <ps@pks.im>
---
 Documentation/MyFirstContribution.adoc | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

The b4 tool originates from the Linux kernel community and is intended to help mailing-list based workflows. It automates a lot of the annoying bookkeeping tasks that contributors typically need to do: tracking the list of recipients, Message-IDs, range-diffs and the like. In addition to that, b4 also has many other subcommands that help the maintainer and reviewers.

The Git project uses the same infrastructure as the kernel, so this tool is also a very good fit for us. Adapt "MyFirstContribution" to explicitly recommend its use.

Signed-off-by: Patrick Steinhardt <ps@pks.im>
---
 Documentation/MyFirstContribution.adoc | 92 ++++++++++++++++++++++++++++++++--
 Documentation/SubmittingPatches        |  6 ++-
 2 files changed, 93 insertions(+), 5 deletions(-)

In the preceding commit we have extended our documentation to recommend b4 for sending patch series to the mailing list. Introduce configuration so that it knows to honor preferences of the Git project by default. For now, this configuration does two things:

  - It configures "send-same-thread = shallow", which tells b4 to always
    send subsequent versions of the same patch series as a reply to the
    cover letter of the first version.

  - It configures "prep-cover-template", which tells b4 to use a custom
    template for the cover letter. The most important change compared to
    the default template is that our custom template also includes a
    range-diff.

There's potentially more things that we may want to configure going forward, like for example auto-configuration of folks to Cc on certain patches. But these two tweaks feel like a good place to start.

Note that these values only serve as defaults, and users may want to tweak those defaults based on their own preference. Luckily, users can do that without having to touch `.b4-config` at all, as b4 allows them to override values via Git configuration:

    ```
    $ git config set b4.prep-cover-template /does/not/exist
    $ b4 send --dry-run
    ERROR: prep-cover-template says to use x, but it does not exist
    ```

So this gives users an easy way to override our defaults without having to touch ".b4-config", which would dirty the tree.

Signed-off-by: Patrick Steinhardt <ps@pks.im>
---
 .b4-config         |  6 ++++++
 .b4-cover-template | 11 +++++++++++
 2 files changed, 17 insertions(+)

Patrick Steinhardt <ps@pks.im> writes:

No further comments based on the range-diff.