{"thread":{"id":"65738","subject":"[PATCH 0/2] Documentation: recommend the use of b4","startedAt":"2026-06-02T11:59:33Z","lastAt":"2026-06-16T06:40:26Z","messageCount":54,"participants":["Patrick Steinhardt","Junio C Hamano","Weijie Yuan","Ramsay Jones","Tuomas Ahola","SZEDER Gábor","Toon Claes","Kristoffer Haugsbakk","Karthik Nayak"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"544495","messageId":"20260602-pks-b4-v1-1-a7ae5a49e9cf@pks.im","threadId":"65738","inReplyTo":"20260602-pks-b4-v1-0-a7ae5a49e9cf@pks.im","subject":"[PATCH 1/2] b4: introduce configuration for the Git project","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-06-02T11:59:09Z","receivedAt":"2026-06-02T11:59:32Z","isPatch":true,"body":"We're about to extend our documentation to recommend b4 for sending\npatch series ot the mailing list. Prepare for this by introducing a b4\nconfiguration so that the tool knows to honor our preferences. For now,\nthis configuration does two things:\n\n - It configures \"send-same-thread = shallow\", which tells b4 to always\n send subsequent versions of the same patch series as a reply to the\n cover letter of the first version.\n\n - It configures \"prep-cover-template\", which tells b4 to use a custom\n template for the cover letter. The most important change compared to\n the default template is that our custom template also includes a\n range-diff.\n\nThere's potentially more things that we may want to configure going\nforward, like for example auto-configuration of folks to Cc on certain\npatches. But these two tweaks feel like a good place to start.\n\nSigned-off-by: Patrick Steinhardt \n---\n .b4-config | 3 +++\n .b4-cover-template | 11 +++++++++++\n 2 files changed, 14 insertions(+)\n\ndiff --git a/.b4-config b/.b4-config\nnew file mode 100644\nindex 0000000000..14124728ce\n--- /dev/null\n+++ b/.b4-config\n@@ -0,0 +1,3 @@\n+[b4]\n+send-same-thread = shallow\n+prep-cover-template = ./.b4-cover-template\ndiff --git a/.b4-cover-template b/.b4-cover-template\nnew file mode 100644\nindex 0000000000..ab864933b5\n--- /dev/null\n+++ b/.b4-cover-template\n@@ -0,0 +1,11 @@\n+${cover}\n+\n+---\n+${shortlog}\n+\n+${diffstat}\n+\n+${range_diff}\n+---\n+base-commit: ${base_commit}\n+${prerequisites}\n\n-- \n2.54.0.1064.gd145956f57.dirty\n\n"},{"id":"544494","messageId":"20260602-pks-b4-v1-0-a7ae5a49e9cf@pks.im","threadId":"65738","inReplyTo":null,"subject":"[PATCH 0/2] Documentation: recommend the use of b4","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-06-02T11:59:08Z","receivedAt":"2026-06-02T11:59:33Z","isPatch":true,"body":"Hi,\n\nthis small patch series wires up b4 in Git and recommends the use\nthereof via \"MyFirstContribution\", as discussed in [1].\n\nThanks!\n\nPatrick\n\n[1]: \n\n---\nPatrick Steinhardt (2):\n b4: introduce configuration for the Git project\n Documentation/MyFirstContribution: recommend the use of b4\n\n .b4-config | 3 ++\n .b4-cover-template | 11 +++++\n Documentation/MyFirstContribution.adoc | 81 ++++++++++++++++++++++++++++++++--\n Documentation/SubmittingPatches | 6 ++-\n 4 files changed, 96 insertions(+), 5 deletions(-)\n\n\n---\nbase-commit: 9ac3f193c05c2237e2b14ebaa1149e9fc8a1abe0\nchange-id: 20260602-pks-b4-31cc20d7f84b\n\n"},{"id":"544496","messageId":"20260602-pks-b4-v1-2-a7ae5a49e9cf@pks.im","threadId":"65738","inReplyTo":"20260602-pks-b4-v1-0-a7ae5a49e9cf@pks.im","subject":"[PATCH 2/2] Documentation/MyFirstContribution: recommend the use of b4","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-06-02T11:59:10Z","receivedAt":"2026-06-02T11:59:34Z","isPatch":true,"body":"The b4 tool originates from the Linux kernel community and is intended\nto help mailing-list based workflows. It automates a lot of the annoying\nbookkeeping tasks that contributors typically need to do: tracking the\nlist of recipients, Message-IDs, range-diffs and the like. In addition\nto that, b4 also has many other subcommands that help the maintainer and\nreviewers.\n\nThe Git project uses the same infrastructure as the kernel, so this tool\nis also a very good fit for us. Adapt \"MyFirstContribution\" to\nexplicitly recommend its use.\n\nSigned-off-by: Patrick Steinhardt \n---\n Documentation/MyFirstContribution.adoc | 81 ++++++++++++++++++++++++++++++++--\n Documentation/SubmittingPatches | 6 ++-\n 2 files changed, 82 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc\nindex b9fdefce02..2e50111d89 100644\n--- a/Documentation/MyFirstContribution.adoc\n+++ b/Documentation/MyFirstContribution.adoc\n@@ -833,7 +833,7 @@ This patchset is part of the MyFirstContribution tutorial and should not\n be merged.\n ----\n \n-At this point the tutorial diverges, in order to demonstrate two\n+At this point the tutorial diverges, in order to demonstrate three\n different methods of formatting your patchset and getting it reviewed.\n \n The first method to be covered is GitGitGadget, which is useful for those\n@@ -845,9 +845,14 @@ more fine-grained control over the emails to be sent. This method requires some\n setup which can change depending on your system and will not be covered in this\n tutorial.\n \n+The third method to be covered is `b4`, which builds on top of `git\n+format-patch` and `git send-email`. This method is the recommended way to\n+submit patches via mail as it automates a lot of the bookkeeping required by\n+`git send-email`.\n+\n Regardless of which method you choose, your engagement with reviewers will be\n-the same; the review process will be covered after the sections on GitGitGadget\n-and `git send-email`.\n+the same; the review process will be covered after the sections on GitGitGadget,\n+`git send-email` and `b4`.\n \n [[howto-ggg]]\n == Sending Patches via GitGitGadget\n@@ -1296,6 +1301,76 @@ index 88f126184c..38da593a60 100644\n 2.21.0.392.gf8f6787159e-goog\n ----\n \n+[[howto-b4]]\n+== Sending Patches with `b4`\n+\n+`b4` is a tool that builds on top of `git format-patch` and `git send-email`.\n+It automates much of the bookkeeping involved in sending a patch series to a\n+mailing-list-based project.\n+\n+Refer to the https://b4.docs.kernel.org/[b4 documentation] for a full reference.\n+\n+[[prep-b4]]\n+=== Preparing a Patch Series\n+\n+`b4` tracks your patch series as a branch. To start tracking the `psuh` branch\n+you have been working on, run:\n+\n+----\n+$ b4 prep --enroll master\n+----\n+\n+This enrolls the current branch, using `master` as the base of the topic. `b4`\n+manages the cover letter as part of the branch, so you can edit it at any time\n+with:\n+\n+----\n+$ b4 prep --edit-cover\n+----\n+\n+The cover letter not only tracks the content of the top-level mail, but also\n+the set of recipients. You can add recipients by adding `To:` and `Cc:`\n+trailer lines.\n+\n+[[send-b4]]\n+=== Sending the Patches\n+\n+Before sending the series out for real, you can inspect what `b4` would send by\n+passing `--dry-run`:\n+\n+----\n+$ b4 send --dry-run\n+----\n+\n+Once you are happy with the result, send the series with:\n+\n+----\n+$ b4 send\n+----\n+\n+[[v2-b4]]\n+=== Sending v2\n+\n+When you are ready to send a new iteration of your series, refine your\n+patches as usual using linkgit:git-rebase[1]. Note that you typically want to\n+rebase on top of the cover letter. You can configure an alias to enable easy\n+rebases going forward:\n+\n+---\n+$ git config set alias.b4-rebase 'rebase \"HEAD^{/--- b4-submit-tracking ---}\"'\n+$ git b4-rebase -i\n+---\n+\n+Before sending out the new version you should also update the cover letter with\n+`b4 prep --edit-cover` to note the relevant changes compared to the previous\n+version. You can inspect the changes between the two versions with `b4 prep\n+--compare-to=v1`.\n+\n+Same as with the first version, you can use `b4 send` to send out the second\n+version. `b4` automatically bumps the version to `v2`, generates the range-diff\n+against the previous iteration, and threads the new series as a reply to the\n+cover letter of the first version.\n+\n [[now-what]]\n == My Patch Got Emailed - Now What?\n \ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex d570184ec8..99427e1ee1 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -573,8 +573,10 @@ your existing e-mail client (often optimized for \"multipart/*\" MIME\n type e-mails) might render your patches unusable.\n \n NOTE: Here we outline the procedure using `format-patch` and\n-`send-email`, but you can instead use GitGitGadget to send in your\n-patches (see link:MyFirstContribution.html[MyFirstContribution]).\n+`send-email`, but you can instead use GitGitGadget or `b4` to send in\n+your patches (see link:MyFirstContribution.html[MyFirstContribution]).\n+Contributors are encouraged to use `b4`, which automates much of the\n+bookkeeping that is otherwise done by hand.\n \n People on the Git mailing list need to be able to read and\n comment on the changes you are submitting. It is important for\n\n-- \n2.54.0.1064.gd145956f57.dirty\n\n"},{"id":"544507","messageId":"xmqqldcxvziw.fsf@gitster.g","threadId":"65738","inReplyTo":"20260602-pks-b4-v1-1-a7ae5a49e9cf@pks.im","subject":"Re: [PATCH 1/2] b4: introduce configuration for the Git project","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-06-02T13:32:23Z","receivedAt":"2026-06-02T13:32:26Z","isPatch":true,"body":"Patrick Steinhardt writes:\n\n> We're about to extend our documentation to recommend b4 for sending\n> patch series ot the mailing list. Prepare for this by introducing a b4\n> configuration so that the tool knows to honor our preferences. For now,\n> this configuration does two things:\n>\n> - It configures \"send-same-thread = shallow\", which tells b4 to always\n> send subsequent versions of the same patch series as a reply to the\n> cover letter of the first version.\n>\n> - It configures \"prep-cover-template\", which tells b4 to use a custom\n> template for the cover letter. The most important change compared to\n> the default template is that our custom template also includes a\n> range-diff.\n>\n> There's potentially more things that we may want to configure going\n> forward, like for example auto-configuration of folks to Cc on certain\n> patches. But these two tweaks feel like a good place to start.\n>\n> Signed-off-by: Patrick Steinhardt \n> ---\n> .b4-config | 3 +++\n> .b4-cover-template | 11 +++++++++++\n> 2 files changed, 14 insertions(+)\n\nShipping a sample like \".b4-config.sample\" that users who opt-in can\ncopy-and-edit into the final name \".b4-config\" is OK, but I'd rather\nnot to ship the configuration files that the users would want to edit\n(hence making the tree dirty).\n"},{"id":"544525","messageId":"ah7vKc8XTKdpcHuH@pks.im","threadId":"65738","inReplyTo":"xmqqldcxvziw.fsf@gitster.g","subject":"Re: [PATCH 1/2] b4: introduce configuration for the Git project","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-06-02T14:56:41Z","receivedAt":"2026-06-02T14:56:48Z","isPatch":true,"body":"On Tue, Jun 02, 2026 at 10:32:23PM +0900, Junio C Hamano wrote:\n> Patrick Steinhardt writes:\n> \n> > We're about to extend our documentation to recommend b4 for sending\n> > patch series ot the mailing list. Prepare for this by introducing a b4\n> > configuration so that the tool knows to honor our preferences. For now,\n> > this configuration does two things:\n> >\n> > - It configures \"send-same-thread = shallow\", which tells b4 to always\n> > send subsequent versions of the same patch series as a reply to the\n> > cover letter of the first version.\n> >\n> > - It configures \"prep-cover-template\", which tells b4 to use a custom\n> > template for the cover letter. The most important change compared to\n> > the default template is that our custom template also includes a\n> > range-diff.\n> >\n> > There's potentially more things that we may want to configure going\n> > forward, like for example auto-configuration of folks to Cc on certain\n> > patches. But these two tweaks feel like a good place to start.\n> >\n> > Signed-off-by: Patrick Steinhardt \n> > ---\n> > .b4-config | 3 +++\n> > .b4-cover-template | 11 +++++++++++\n> > 2 files changed, 14 insertions(+)\n> \n> Shipping a sample like \".b4-config.sample\" that users who opt-in can\n> copy-and-edit into the final name \".b4-config\" is OK, but I'd rather\n> not to ship the configuration files that the users would want to edit\n> (hence making the tree dirty).\n\nI think shipping this as-is makes sense though, as it allows us to make\nb4 behave the way we want it to without the user having to do anything.\nIf users actually want to reconfigure those values they can by saying\n`git config set b4.`, as the repository-local configuration will\noverride whatever `.b4-config` has.\n\nPatrick\n"},{"id":"544530","messageId":"ah8ALHMDVA2Gzz10@wyuan.org","threadId":"65738","inReplyTo":"20260602-pks-b4-v1-2-a7ae5a49e9cf@pks.im","subject":"Re: [PATCH 2/2] Documentation/MyFirstContribution: recommend the use of b4","fromName":"Weijie Yuan","fromEmail":"wy@wyuan.org","sentAt":"2026-06-02T16:09:16Z","receivedAt":"2026-06-02T16:09:38Z","isPatch":true,"body":"Hi Patrick and Junio,\n\nJust so happens that I just submitted my first patch. At this point, I\nmay or should be the target audience for this document.\n\nI personally watched Patrick's videos with Scott Chacon[1] first, and I\nreviewed them many times until I could do those \"manual\" git operations.\n\n> +Contributors are encouraged to use `b4`, which automates much of the\n> +bookkeeping that is otherwise done by hand.\n\nSo for statement like this and with my personal experience, I would say\nb4 is a more suitable option for senior contributors, as they already\nknow, for example, what Message-ID and range-diffs are. But apparently,\nwhose who use forges may not know.\n\nBack to the patch, I think regarding b4 as a more advanced contribution\nway for those who had contributed via mailing lists for more than one\ntime is a better expression or formulation. Here I mean \"b4 prep\", other\nusage like \"b4 mbox\" and \"b4 am\" are of course more basic, and be\nmentioned as tips when interacting with Git mailing list.\n\nA bit too wordy, in conclusion: Suggest that new contributors master\nclassic git operations first. When they are familiar with those process,\nb4 might be a good option.\n\nThanks!\n--\n[1] https://www.youtube.com/watch?v=mjYac9SwIK0&t=1s (Part 1)\n"},{"id":"544532","messageId":"8dbdb553-9633-46bb-8a51-040d06d0d10e@ramsayjones.plus.com","threadId":"65738","inReplyTo":"xmqqldcxvziw.fsf@gitster.g","subject":"Re: [PATCH 1/2] b4: introduce configuration for the Git project","fromName":"Ramsay Jones","fromEmail":"ramsay@ramsayjones.plus.com","sentAt":"2026-06-02T16:23:16Z","receivedAt":"2026-06-02T16:26:27Z","isPatch":true,"body":"\n\nOn 02/06/2026 2:32 pm, Junio C Hamano wrote:\n> Patrick Steinhardt writes:\n> \n>> We're about to extend our documentation to recommend b4 for sending\n>> patch series ot the mailing list. Prepare for this by introducing a b4\n>> configuration so that the tool knows to honor our preferences. For now,\n>> this configuration does two things:\n>>\n>> - It configures \"send-same-thread = shallow\", which tells b4 to always\n>> send subsequent versions of the same patch series as a reply to the\n>> cover letter of the first version.\n>>\n>> - It configures \"prep-cover-template\", which tells b4 to use a custom\n>> template for the cover letter. The most important change compared to\n>> the default template is that our custom template also includes a\n>> range-diff.\n>>\n>> There's potentially more things that we may want to configure going\n>> forward, like for example auto-configuration of folks to Cc on certain\n>> patches. But these two tweaks feel like a good place to start.\n>>\n>> Signed-off-by: Patrick Steinhardt \n>> ---\n>> .b4-config | 3 +++\n>> .b4-cover-template | 11 +++++++++++\n>> 2 files changed, 14 insertions(+)\n> \n> Shipping a sample like \".b4-config.sample\" that users who opt-in can\n> copy-and-edit into the final name \".b4-config\" is OK, but I'd rather\n> not to ship the configuration files that the users would want to edit\n> (hence making the tree dirty).\n> \n\nHmm, for those of us not in the know, perhaps mention the b4 documentation\nat 'b4.docs.kernel.org' (which includes how to install b4 ... ;) ).\n\nATB,\nRamsay Jones\n\n\n\n"},{"id":"544536","messageId":"20260602170955.Z4b7y%taahol@utu.fi","threadId":"65738","inReplyTo":"20260602-pks-b4-v1-1-a7ae5a49e9cf@pks.im","subject":"Re: [PATCH 1/2] b4: introduce configuration for the Git project","fromName":"Tuomas Ahola","fromEmail":"taahol@utu.fi","sentAt":"2026-06-02T17:09:55Z","receivedAt":"2026-06-02T17:10:13Z","isPatch":true,"body":"Patrick Steinhardt wrote:\n\n> We're about to extend our documentation to recommend b4 for sending\n> patch series ot the mailing list. Prepare for this by introducing a b4\n\ns/ot/to/\n\n> configuration so that the tool knows to honor our preferences. For now,\n> this configuration does two things:\n> \n> - It configures \"send-same-thread = shallow\", which tells b4 to always\n> send subsequent versions of the same patch series as a reply to the\n> cover letter of the first version.\n> \n\nHuh? Doesn't MyFirstContribution speak *against* shallow threading?\n\n\t [...] make sure to replace it with the correct Message-ID for your\n\t**previous cover letter** - that is, if you're sending v2, use the Message-ID\n\tfrom v1; if you're sending v3, use the Message-ID from v2.\n\nBesides, GitGitGadget also employs that kind of nested threading, if I'm\nnot mistaken.\n\nThanks.\n"},{"id":"544569","messageId":"ah-Nhr2PboWUq6eU@wyuan.org","threadId":"65738","inReplyTo":"20260602170955.Z4b7y%taahol@utu.fi","subject":"Re: [PATCH 1/2] b4: introduce configuration for the Git project","fromName":"Weijie Yuan","fromEmail":"wy@wyuan.org","sentAt":"2026-06-03T02:12:22Z","receivedAt":"2026-06-03T02:12:39Z","isPatch":true,"body":"On Tue, Jun 02, 2026 at 08:09:55PM +0300, Tuomas Ahola wrote:\n> Huh? Doesn't MyFirstContribution speak *against* shallow threading?\n>\n> \t [...] make sure to replace it with the correct Message-ID for your\n> \t**previous cover letter** - that is, if you're sending v2, use the Message-ID\n> \tfrom v1; if you're sending v3, use the Message-ID from v2.\n\nI don't get it. Doesn't shallow threading means every following patches\nare replying to the cover letter? Replying to the previous one is\n--chain-reply-to, if I'm not mistaken.\n\nThanks.\n"},{"id":"544570","messageId":"871peopbvf.fsf@gitster.g","threadId":"65738","inReplyTo":"8dbdb553-9633-46bb-8a51-040d06d0d10e@ramsayjones.plus.com","subject":"Re: [PATCH 1/2] b4: introduce configuration for the Git project","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-06-03T02:59:48Z","receivedAt":"2026-06-03T02:59:55Z","isPatch":true,"body":"Ramsay Jones writes:\n\n> On 02/06/2026 2:32 pm, Junio C Hamano wrote:\n>> Patrick Steinhardt writes:\n>> \n>>> We're about to extend our documentation to recommend b4 for sending\n>>> patch series ot the mailing list. Prepare for this by introducing a b4\n>>> configuration so that the tool knows to honor our preferences. For now,\n>>> this configuration does two things:\n>>> ...\n>> (hence making the tree dirty).\n>\n> Hmm, for those of us not in the know, perhaps mention the b4 documentation\n> at 'b4.docs.kernel.org' (which includes how to install b4 ... ;) ).\n\nThanks for raising an excellent point.\n"},{"id":"544576","messageId":"ah_PPuX1aVc4CtWb@pks.im","threadId":"65738","inReplyTo":"871peopbvf.fsf@gitster.g","subject":"Re: [PATCH 1/2] b4: introduce configuration for the Git project","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-06-03T06:52:46Z","receivedAt":"2026-06-03T06:52:58Z","isPatch":true,"body":"On Wed, Jun 03, 2026 at 11:59:48AM +0900, Junio C Hamano wrote:\n> Ramsay Jones writes:\n> \n> > On 02/06/2026 2:32 pm, Junio C Hamano wrote:\n> >> Patrick Steinhardt writes:\n> >> \n> >>> We're about to extend our documentation to recommend b4 for sending\n> >>> patch series ot the mailing list. Prepare for this by introducing a b4\n> >>> configuration so that the tool knows to honor our preferences. For now,\n> >>> this configuration does two things:\n> >>> ...\n> >> (hence making the tree dirty).\n> >\n> > Hmm, for those of us not in the know, perhaps mention the b4 documentation\n> > at 'b4.docs.kernel.org' (which includes how to install b4 ... ;) ).\n> \n> Thanks for raising an excellent point.\n\nI already refer to the docs in the second commit. Let me maybe reorder\nthem so that we first show how it's used before tweaking it.\n\nPatrick\n"},{"id":"544577","messageId":"ah_PwOsbYfDCx0H2@pks.im","threadId":"65738","inReplyTo":"ah8ALHMDVA2Gzz10@wyuan.org","subject":"Re: [PATCH 2/2] Documentation/MyFirstContribution: recommend the use of b4","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-06-03T06:54:56Z","receivedAt":"2026-06-03T06:55:01Z","isPatch":true,"body":"On Wed, Jun 03, 2026 at 12:09:16AM +0800, Weijie Yuan wrote:\n> > +Contributors are encouraged to use `b4`, which automates much of the\n> > +bookkeeping that is otherwise done by hand.\n> \n> So for statement like this and with my personal experience, I would say\n> b4 is a more suitable option for senior contributors, as they already\n> know, for example, what Message-ID and range-diffs are. But apparently,\n> whose who use forges may not know.\n\nI think it's perfectly suitable for newcomers, too. It automates so many\nof the concepts that a contributor has to learn way less about mailing\nlist specific concepts, which reduces the learning curve.\n\n> Back to the patch, I think regarding b4 as a more advanced contribution\n> way for those who had contributed via mailing lists for more than one\n> time is a better expression or formulation. Here I mean \"b4 prep\", other\n> usage like \"b4 mbox\" and \"b4 am\" are of course more basic, and be\n> mentioned as tips when interacting with Git mailing list.\n> \n> A bit too wordy, in conclusion: Suggest that new contributors master\n> classic git operations first. When they are familiar with those process,\n> b4 might be a good option.\n\nAh, that's what you're hinting at. So you mean to say that folks should\nfirst understand the basics before basically automating all of the parts\nfor them?\n\nI guess I can see where you're coming from, but I'm not sure I agree\nwith this a 100%. My main goal is to make it easier for new community\nmembers to contribute to Git, and that means that we should automate all\nthe hard parts as far as possible. This saves those new contributors\nfrom frustration, and it means that reviewers on the mailing list won't\nhave to teach every single new contributor about how they should thread\nthe mails, generate range-diffs and the like.\n\nSo in the end, it saves both their and our time, but the learning\nopportunity is of course a bit diminished. I'd gladly accept that\ntradeoff though.\n\nThanks for your input!\n\nPatrick\n"},{"id":"544578","messageId":"ah_PyDwO1Sffr5yq@pks.im","threadId":"65738","inReplyTo":"ah-Nhr2PboWUq6eU@wyuan.org","subject":"Re: [PATCH 1/2] b4: introduce configuration for the Git project","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-06-03T06:55:04Z","receivedAt":"2026-06-03T06:55:09Z","isPatch":true,"body":"On Wed, Jun 03, 2026 at 10:12:22AM +0800, Weijie Yuan wrote:\n> On Tue, Jun 02, 2026 at 08:09:55PM +0300, Tuomas Ahola wrote:\n> > Huh? Doesn't MyFirstContribution speak *against* shallow threading?\n> >\n> > \t [...] make sure to replace it with the correct Message-ID for your\n> > \t**previous cover letter** - that is, if you're sending v2, use the Message-ID\n> > \tfrom v1; if you're sending v3, use the Message-ID from v2.\n> \n> I don't get it. Doesn't shallow threading means every following patches\n> are replying to the cover letter? Replying to the previous one is\n> --chain-reply-to, if I'm not mistaken.\n\nShallow threading basically means that all patches are sent as a\nresponse to the current cover letter, and the current cover letter is\nalways attached to the cover letter of the _first_ version.\n\nSo this quote is definitely at odds with the configuration I have\nproposed. It's actually quite surprising to me that we recommend deep\nthreading -- I personally find it extremely hard to navigate as the\nnesting eventually gets way too deep.\n\nYou know -- I'll include a patch that changes the wording there to also\nuse shallow nesting, mostly to kick off a discussion and arrive at a\ndecision there.\n\nThanks!\n\nPatrick\n"},{"id":"544579","messageId":"20260603-pks-b4-v2-0-a8aea0aa2c23@pks.im","threadId":"65738","inReplyTo":"20260602-pks-b4-v1-0-a7ae5a49e9cf@pks.im","subject":"[PATCH v2 0/3] Documentation: recommend the use of b4","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-06-03T06:58:58Z","receivedAt":"2026-06-03T06:59:10Z","isPatch":true,"body":"Hi,\n\nthis small patch series wires up b4 in Git and recommends the use\nthereof via \"MyFirstContribution\", as discussed in [1].\n\nChanges in v2:\n - Reorder commits so that the b4 docs are added first.\n - Add a section that highlights how to configure b4, and that points\n out that the per-project defaults can be overridden via Git\n configuration.\n - Add a patch to MyFirstContribution that recommends shallow\n threading. I mostly intend this to be a discussion starter so that\n the `.b4-config` file matches our preferred threading style.\n - Fix a typo.\n - Link to v1: https://patch.msgid.link/20260602-pks-b4-v1-0-a7ae5a49e9cf@pks.im\n\nThanks!\n\nPatrick\n\n[1]: \n\n---\nPatrick Steinhardt (3):\n Documentation/MyFirstContribution: recommend shallow threading\n Documentation/MyFirstContribution: recommend the use of b4\n b4: introduce configuration for the Git project\n\n .b4-config | 6 +++\n .b4-cover-template | 11 ++++\n Documentation/MyFirstContribution.adoc | 96 ++++++++++++++++++++++++++++++++--\n Documentation/SubmittingPatches | 6 ++-\n 4 files changed, 112 insertions(+), 7 deletions(-)\n\nRange-diff versus v1:\n\n-: ---------- > 1: 359ce9ec24 Documentation/MyFirstContribution: recommend shallow threading\n2: 55fffeb8f8 ! 2: ce9aa56846 Documentation/MyFirstContribution: recommend the use of b4\n @@ Documentation/MyFirstContribution.adoc: index 88f126184c..38da593a60 100644\n +version. `b4` automatically bumps the version to `v2`, generates the range-diff\n +against the previous iteration, and threads the new series as a reply to the\n +cover letter of the first version.\n ++\n ++[[configure-b4]]\n ++=== Configure b4\n ++\n ++`b4` can be configured via linkgit:git-config[1]. In addition to that, projects\n ++can have their own set of defaults in `.b4-config` in the root tree, which also\n ++uses Git's config format. The user's configuration always takes precedence over\n ++the per-project defaults.\n ++\n ++Refer to the https://b4.docs.kernel.org/en/latest/config.html[b4 config documentation]\n ++for more information on the available options.\n +\n [[now-what]]\n == My Patch Got Emailed - Now What?\n1: 0fe6cf8511 ! 3: e2bf7b6e46 b4: introduce configuration for the Git project\n @@ Commit message\n b4: introduce configuration for the Git project\n \n We're about to extend our documentation to recommend b4 for sending\n - patch series ot the mailing list. Prepare for this by introducing a b4\n + patch series to the mailing list. Prepare for this by introducing a b4\n configuration so that the tool knows to honor our preferences. For now,\n this configuration does two things:\n \n @@ Commit message\n forward, like for example auto-configuration of folks to Cc on certain\n patches. But these two tweaks feel like a good place to start.\n \n + Note that these values only serve as defaults, and users may want to\n + tweak those defaults based on their own preference. Luckily, users can\n + do that without having to touch `.b4-config` at all, as b4 allows them\n + to override values via Git configuration:\n +\n + ```\n + $ git config set b4.prep-cover-template /does/not/exist\n + $ b4 send --dry-run\n + ERROR: prep-cover-template says to use x, but it does not exist\n + ```\n +\n + So this gives users an easy way to override our defaults without having\n + to touch \".b4-config\", which would dirty the tree.\n +\n Signed-off-by: Patrick Steinhardt \n \n ## .b4-config (new) ##\n @@\n ++# Note that these are default values that you can tweak via the typical\n ++# git-config(1) machinery. You thus shouldn't ever have to change this file.\n ++# See also https://b4.docs.kernel.org/en/latest/config.html.\n +[b4]\n +send-same-thread = shallow\n +prep-cover-template = ./.b4-cover-template\n\n---\nbase-commit: 9ac3f193c05c2237e2b14ebaa1149e9fc8a1abe0\nchange-id: 20260602-pks-b4-31cc20d7f84b\n\n"},{"id":"544580","messageId":"20260603-pks-b4-v2-1-a8aea0aa2c23@pks.im","threadId":"65738","inReplyTo":"20260603-pks-b4-v2-0-a8aea0aa2c23@pks.im","subject":"[PATCH v2 1/3] Documentation/MyFirstContribution: recommend shallow threading","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-06-03T06:58:59Z","receivedAt":"2026-06-03T06:59:12Z","isPatch":true,"body":"The \"MyFirstContribution\" document recommends the use of deep threading:\nevery cover letter of subsequent iterations shall be linked to the cover\nletter of the preceding version. The result of this is that eventually,\nthreads with many versions are getting nested so deep that it becomes\nhard to follow.\n\nAdapt the recommendation to instead propose shallow threading: instead\nof linking the cover letter to the previous cover letter, the user is\nsupposed to always link it to the first cover letter. This still makes\nit easy to follow the iterations, but has the benefit of nesting to a\nmuch shallower level.\n\nSigned-off-by: Patrick Steinhardt \n---\n Documentation/MyFirstContribution.adoc | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc\nindex b9fdefce02..069020196c 100644\n--- a/Documentation/MyFirstContribution.adoc\n+++ b/Documentation/MyFirstContribution.adoc\n@@ -1227,8 +1227,8 @@ Message-ID: \n \n Your Message-ID is ``. This example will be used\n below as well; make sure to replace it with the correct Message-ID for your\n-**previous cover letter** - that is, if you're sending v2, use the Message-ID\n-from v1; if you're sending v3, use the Message-ID from v2.\n+**first cover letter** - that is, for any subsequent version that you send,\n+always use the Message-ID from v1.\n \n While you're looking at the email, you should also note who is CC'd, as it's\n common practice in the mailing list to keep all CCs on a thread. You can add\n\n-- \n2.54.0.1064.gd145956f57.dirty\n\n"},{"id":"544581","messageId":"20260603-pks-b4-v2-2-a8aea0aa2c23@pks.im","threadId":"65738","inReplyTo":"20260603-pks-b4-v2-0-a8aea0aa2c23@pks.im","subject":"[PATCH v2 2/3] Documentation/MyFirstContribution: recommend the use of b4","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-06-03T06:59:00Z","receivedAt":"2026-06-03T06:59:14Z","isPatch":true,"body":"The b4 tool originates from the Linux kernel community and is intended\nto help mailing-list based workflows. It automates a lot of the annoying\nbookkeeping tasks that contributors typically need to do: tracking the\nlist of recipients, Message-IDs, range-diffs and the like. In addition\nto that, b4 also has many other subcommands that help the maintainer and\nreviewers.\n\nThe Git project uses the same infrastructure as the kernel, so this tool\nis also a very good fit for us. Adapt \"MyFirstContribution\" to\nexplicitly recommend its use.\n\nSigned-off-by: Patrick Steinhardt \n---\n Documentation/MyFirstContribution.adoc | 92 ++++++++++++++++++++++++++++++++--\n Documentation/SubmittingPatches | 6 ++-\n 2 files changed, 93 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc\nindex 069020196c..fc0b06ae67 100644\n--- a/Documentation/MyFirstContribution.adoc\n+++ b/Documentation/MyFirstContribution.adoc\n@@ -833,7 +833,7 @@ This patchset is part of the MyFirstContribution tutorial and should not\n be merged.\n ----\n \n-At this point the tutorial diverges, in order to demonstrate two\n+At this point the tutorial diverges, in order to demonstrate three\n different methods of formatting your patchset and getting it reviewed.\n \n The first method to be covered is GitGitGadget, which is useful for those\n@@ -845,9 +845,14 @@ more fine-grained control over the emails to be sent. This method requires some\n setup which can change depending on your system and will not be covered in this\n tutorial.\n \n+The third method to be covered is `b4`, which builds on top of `git\n+format-patch` and `git send-email`. This method is the recommended way to\n+submit patches via mail as it automates a lot of the bookkeeping required by\n+`git send-email`.\n+\n Regardless of which method you choose, your engagement with reviewers will be\n-the same; the review process will be covered after the sections on GitGitGadget\n-and `git send-email`.\n+the same; the review process will be covered after the sections on GitGitGadget,\n+`git send-email` and `b4`.\n \n [[howto-ggg]]\n == Sending Patches via GitGitGadget\n@@ -1296,6 +1301,87 @@ index 88f126184c..38da593a60 100644\n 2.21.0.392.gf8f6787159e-goog\n ----\n \n+[[howto-b4]]\n+== Sending Patches with `b4`\n+\n+`b4` is a tool that builds on top of `git format-patch` and `git send-email`.\n+It automates much of the bookkeeping involved in sending a patch series to a\n+mailing-list-based project.\n+\n+Refer to the https://b4.docs.kernel.org/[b4 documentation] for a full reference.\n+\n+[[prep-b4]]\n+=== Preparing a Patch Series\n+\n+`b4` tracks your patch series as a branch. To start tracking the `psuh` branch\n+you have been working on, run:\n+\n+----\n+$ b4 prep --enroll master\n+----\n+\n+This enrolls the current branch, using `master` as the base of the topic. `b4`\n+manages the cover letter as part of the branch, so you can edit it at any time\n+with:\n+\n+----\n+$ b4 prep --edit-cover\n+----\n+\n+The cover letter not only tracks the content of the top-level mail, but also\n+the set of recipients. You can add recipients by adding `To:` and `Cc:`\n+trailer lines.\n+\n+[[send-b4]]\n+=== Sending the Patches\n+\n+Before sending the series out for real, you can inspect what `b4` would send by\n+passing `--dry-run`:\n+\n+----\n+$ b4 send --dry-run\n+----\n+\n+Once you are happy with the result, send the series with:\n+\n+----\n+$ b4 send\n+----\n+\n+[[v2-b4]]\n+=== Sending v2\n+\n+When you are ready to send a new iteration of your series, refine your\n+patches as usual using linkgit:git-rebase[1]. Note that you typically want to\n+rebase on top of the cover letter. You can configure an alias to enable easy\n+rebases going forward:\n+\n+---\n+$ git config set alias.b4-rebase 'rebase \"HEAD^{/--- b4-submit-tracking ---}\"'\n+$ git b4-rebase -i\n+---\n+\n+Before sending out the new version you should also update the cover letter with\n+`b4 prep --edit-cover` to note the relevant changes compared to the previous\n+version. You can inspect the changes between the two versions with `b4 prep\n+--compare-to=v1`.\n+\n+Same as with the first version, you can use `b4 send` to send out the second\n+version. `b4` automatically bumps the version to `v2`, generates the range-diff\n+against the previous iteration, and threads the new series as a reply to the\n+cover letter of the first version.\n+\n+[[configure-b4]]\n+=== Configure b4\n+\n+`b4` can be configured via linkgit:git-config[1]. In addition to that, projects\n+can have their own set of defaults in `.b4-config` in the root tree, which also\n+uses Git's config format. The user's configuration always takes precedence over\n+the per-project defaults.\n+\n+Refer to the https://b4.docs.kernel.org/en/latest/config.html[b4 config documentation]\n+for more information on the available options.\n+\n [[now-what]]\n == My Patch Got Emailed - Now What?\n \ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex d570184ec8..99427e1ee1 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -573,8 +573,10 @@ your existing e-mail client (often optimized for \"multipart/*\" MIME\n type e-mails) might render your patches unusable.\n \n NOTE: Here we outline the procedure using `format-patch` and\n-`send-email`, but you can instead use GitGitGadget to send in your\n-patches (see link:MyFirstContribution.html[MyFirstContribution]).\n+`send-email`, but you can instead use GitGitGadget or `b4` to send in\n+your patches (see link:MyFirstContribution.html[MyFirstContribution]).\n+Contributors are encouraged to use `b4`, which automates much of the\n+bookkeeping that is otherwise done by hand.\n \n People on the Git mailing list need to be able to read and\n comment on the changes you are submitting. It is important for\n\n-- \n2.54.0.1064.gd145956f57.dirty\n\n"},{"id":"544582","messageId":"20260603-pks-b4-v2-3-a8aea0aa2c23@pks.im","threadId":"65738","inReplyTo":"20260603-pks-b4-v2-0-a8aea0aa2c23@pks.im","subject":"[PATCH v2 3/3] b4: introduce configuration for the Git project","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-06-03T06:59:01Z","receivedAt":"2026-06-03T06:59:16Z","isPatch":true,"body":"We're about to extend our documentation to recommend b4 for sending\npatch series to the mailing list. Prepare for this by introducing a b4\nconfiguration so that the tool knows to honor our preferences. For now,\nthis configuration does two things:\n\n - It configures \"send-same-thread = shallow\", which tells b4 to always\n send subsequent versions of the same patch series as a reply to the\n cover letter of the first version.\n\n - It configures \"prep-cover-template\", which tells b4 to use a custom\n template for the cover letter. The most important change compared to\n the default template is that our custom template also includes a\n range-diff.\n\nThere's potentially more things that we may want to configure going\nforward, like for example auto-configuration of folks to Cc on certain\npatches. But these two tweaks feel like a good place to start.\n\nNote that these values only serve as defaults, and users may want to\ntweak those defaults based on their own preference. Luckily, users can\ndo that without having to touch `.b4-config` at all, as b4 allows them\nto override values via Git configuration:\n\n ```\n $ git config set b4.prep-cover-template /does/not/exist\n $ b4 send --dry-run\n ERROR: prep-cover-template says to use x, but it does not exist\n ```\n\nSo this gives users an easy way to override our defaults without having\nto touch \".b4-config\", which would dirty the tree.\n\nSigned-off-by: Patrick Steinhardt \n---\n .b4-config | 6 ++++++\n .b4-cover-template | 11 +++++++++++\n 2 files changed, 17 insertions(+)\n\ndiff --git a/.b4-config b/.b4-config\nnew file mode 100644\nindex 0000000000..fd4fb56b6d\n--- /dev/null\n+++ b/.b4-config\n@@ -0,0 +1,6 @@\n+# Note that these are default values that you can tweak via the typical\n+# git-config(1) machinery. You thus shouldn't ever have to change this file.\n+# See also https://b4.docs.kernel.org/en/latest/config.html.\n+[b4]\n+send-same-thread = shallow\n+prep-cover-template = ./.b4-cover-template\ndiff --git a/.b4-cover-template b/.b4-cover-template\nnew file mode 100644\nindex 0000000000..ab864933b5\n--- /dev/null\n+++ b/.b4-cover-template\n@@ -0,0 +1,11 @@\n+${cover}\n+\n+---\n+${shortlog}\n+\n+${diffstat}\n+\n+${range_diff}\n+---\n+base-commit: ${base_commit}\n+${prerequisites}\n\n-- \n2.54.0.1064.gd145956f57.dirty\n\n"},{"id":"544583","messageId":"ah_c3kgmfRh3bXns@wyuan.org","threadId":"65738","inReplyTo":"ah_PyDwO1Sffr5yq@pks.im","subject":"Re: [PATCH 1/2] b4: introduce configuration for the Git project","fromName":"Weijie Yuan","fromEmail":"wy@wyuan.org","sentAt":"2026-06-03T07:50:54Z","receivedAt":"2026-06-03T07:51:22Z","isPatch":true,"body":"On Wed, Jun 03, 2026 at 08:55:04AM +0200, Patrick Steinhardt wrote:\n> So this quote is definitely at odds with the configuration I have\n> proposed. It's actually quite surprising to me that we recommend deep\n> threading -- I personally find it extremely hard to navigate as the\n> nesting eventually gets way too deep.\n\nSorry I'm a little confused. The example thread at git-scm.com:\n\nhttps://git-scm.com/docs/MyFirstContribution#ready-to-share\n\nIsn't this actually supporting shallow nesting?\n\n> It's actually quite surprising to me that we recommend deep\n> threading -- I personally find it extremely hard to navigate as the\n> nesting eventually gets way too deep.\n\nIn my understanding, deep threading == --chain-reply-to, so can you\npoint out where do Git recommend deep threading? I always thought Git\nsupports shallow threading.\n\nThanks! And please forgive me if I am wrong :-)\n"},{"id":"544584","messageId":"ah_dh3uozNdYcL0_@wyuan.org","threadId":"65738","inReplyTo":"ah_PwOsbYfDCx0H2@pks.im","subject":"Re: [PATCH 2/2] Documentation/MyFirstContribution: recommend the use of b4","fromName":"Weijie Yuan","fromEmail":"wy@wyuan.org","sentAt":"2026-06-03T07:53:43Z","receivedAt":"2026-06-03T07:53:59Z","isPatch":true,"body":"On Wed, Jun 03, 2026 at 08:54:56AM +0200, Patrick Steinhardt wrote:\n> Ah, that's what you're hinting at. So you mean to say that folks should\n> first understand the basics before basically automating all of the parts\n> for them?\n>\n> I guess I can see where you're coming from, but I'm not sure I agree\n> with this a 100%. My main goal is to make it easier for new community\n> members to contribute to Git, and that means that we should automate all\n> the hard parts as far as possible. This saves those new contributors\n> from frustration, and it means that reviewers on the mailing list won't\n> have to teach every single new contributor about how they should thread\n> the mails, generate range-diffs and the like.\n>\n> So in the end, it saves both their and our time, but the learning\n> opportunity is of course a bit diminished. I'd gladly accept that\n> tradeoff though.\n\nYeah, after I expressed my opinion, I also felt a bit conflicted though.\nSo I also agree with your intension.\n\nMake an inappropriate metaphor: some usage of b4 and magit are \"Porcelain\"\nto Git. Whether how you are good at using those porcelains like magit or\nlazygit, in the end, you will eventually have to face git cli one day.\n\nSo the same for b4. If we list these three methods equally and\nsimultaneously, the logic might be not that correct.\n\nYour proposal:\n\n contribution workflow\n |\n -------------------------------------\n | | |\n v v v\nGitGitGadget traditional email b4\n```\n\nBut I would frame it more like this:\n\n contribution workflow\n |\n -------------------------\n | |\n v v\n GitGitGadget traditional email workflow\n \\\n \\\n b4\n\nFor exmaple, If I am at this page the fisrt time:\n https://git-scm.com/docs/MyFirstContribution\nAnd, I see these 3 ways, okay, I choose b4.\n\nAfter installing b4 and reading some manuals, I would wonder: what's\ncover letter? what's Message-ID? So after a while, I would still have to\nlearn those stuff and how b4 indeed optimize those complicated process.\n\nSo, to put it another way.. b4 is developed for high-level maintainers,\nwho are apparently familiar with traditional ways. Therefore b4 saves\ntheir time. But for some beginers like me, I still have to know those\nconcepts first.\n\nBut yeah, there are definitely some people would happily accept b4 and\ncontribute easily. Thus, I agree this tradeoff.\n\n--\nSent before reading v2, hope there's no conflict :-)\n"},{"id":"544585","messageId":"ah_fDKBinqbMt5ZO@wyuan.org","threadId":"65738","inReplyTo":"ah_dh3uozNdYcL0_@wyuan.org","subject":"Re: [PATCH 2/2] Documentation/MyFirstContribution: recommend the use of b4","fromName":"Weijie Yuan","fromEmail":"wy@wyuan.org","sentAt":"2026-06-03T08:00:12Z","receivedAt":"2026-06-03T08:00:37Z","isPatch":true,"body":"That said, my ideas may be too nitpicking. Overall, I do\nthink that introducing b4 support would be a good thing.\n\nThanks for the replies, and for bearing with my questions/comments.\n\nWeijie Yuan\n"},{"id":"544595","messageId":"ah_5PBRZFgQWvkjj@wyuan.org","threadId":"65738","inReplyTo":"ah_c3kgmfRh3bXns@wyuan.org","subject":"Re: [PATCH 1/2] b4: introduce configuration for the Git project","fromName":"Weijie Yuan","fromEmail":"wy@wyuan.org","sentAt":"2026-06-03T09:51:56Z","receivedAt":"2026-06-03T09:52:29Z","isPatch":true,"body":"On Wed, Jun 03, 2026 at 03:51:21PM +0800, Weijie Yuan wrote:\n> On Wed, Jun 03, 2026 at 08:55:04AM +0200, Patrick Steinhardt wrote:\n> > So this quote is definitely at odds with the configuration I have\n> > proposed. It's actually quite surprising to me that we recommend deep\n> > threading -- I personally find it extremely hard to navigate as the\n> > nesting eventually gets way too deep.\n>\n> Sorry I'm a little confused. The example thread at git-scm.com:\n>\n> https://git-scm.com/docs/MyFirstContribution#ready-to-share\n>\n> Isn't this actually supporting shallow nesting?\n>\n> > It's actually quite surprising to me that we recommend deep\n> > threading -- I personally find it extremely hard to navigate as the\n> > nesting eventually gets way too deep.\n>\n> In my understanding, deep threading == --chain-reply-to, so can you\n> point out where do Git recommend deep threading? I always thought Git\n> supports shallow threading.\n>\n> Thanks! And please forgive me if I am wrong :-)\n\nAh, I know you mean the deep nesting of cover letters, sorry, now I\nknow.\n\nThanks!\n"},{"id":"544596","messageId":"20260603100145.7iym5%taahol@utu.fi","threadId":"65738","inReplyTo":"20260603-pks-b4-v2-1-a8aea0aa2c23@pks.im","subject":"Re: [PATCH v2 1/3] Documentation/MyFirstContribution: recommend shallow threading","fromName":"Tuomas Ahola","fromEmail":"taahol@utu.fi","sentAt":"2026-06-03T10:01:45Z","receivedAt":"2026-06-03T10:01:57Z","isPatch":true,"body":"Patrick Steinhardt wrote:\n\n> The \"MyFirstContribution\" document recommends the use of deep threading:\n> every cover letter of subsequent iterations shall be linked to the cover\n> letter of the preceding version. The result of this is that eventually,\n> threads with many versions are getting nested so deep that it becomes\n> hard to follow.\n> \n> Adapt the recommendation to instead propose shallow threading: instead\n> of linking the cover letter to the previous cover letter, the user is\n> supposed to always link it to the first cover letter. This still makes\n> it easy to follow the iterations, but has the benefit of nesting to a\n> much shallower level.\n> \n> Signed-off-by: Patrick Steinhardt \n> ---\n> Documentation/MyFirstContribution.adoc | 4 ++--\n> 1 file changed, 2 insertions(+), 2 deletions(-)\n> \n> diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc\n> index b9fdefce02..069020196c 100644\n> --- a/Documentation/MyFirstContribution.adoc\n> +++ b/Documentation/MyFirstContribution.adoc\n> @@ -1227,8 +1227,8 @@ Message-ID: \n> \n> Your Message-ID is ``. This example will be used\n> below as well; make sure to replace it with the correct Message-ID for your\n> -**previous cover letter** - that is, if you're sending v2, use the Message-ID\n> -from v1; if you're sending v3, use the Message-ID from v2.\n> +**first cover letter** - that is, for any subsequent version that you send,\n> +always use the Message-ID from v1.\n> \n> While you're looking at the email, you should also note who is CC'd, as it's\n> common practice in the mailing list to keep all CCs on a thread. You can add\n> \n> -- \n> 2.54.0.1064.gd145956f57.dirty\n\nIf we adapt this change to the guidance, let's fix also other places of the\ndocument that talk about replying to the previous cover letter.\n\n-----8<-----\n\ndiff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc\nindex 069020196c..bf64a211bd 100644\n--- a/Documentation/MyFirstContribution.adoc\n+++ b/Documentation/MyFirstContribution.adoc\n@@ -790,7 +790,7 @@ We can note a few things:\n v3\", etc. in place of \"PATCH\". For example, \"[PATCH v2 1/3]\" would be the first of\n three patches in the second iteration. Each iteration is sent with a new cover\n letter (like \"[PATCH v2 0/3]\" above), itself a reply to the cover letter of the\n- previous iteration (more on that below).\n+ first iteration (more on that below).\n \n NOTE: A single-patch topic is sent with \"[PATCH]\", \"[PATCH v2]\", etc. without\n _i_/_n_ numbering (in the above thread overview, no single-patch topic appears,\n@@ -1214,7 +1214,7 @@ between your last version and now, if it's something significant. You do not\n need the exact same body in your second cover letter; focus on explaining to\n reviewers the changes you've made that may not be as visible.\n \n-You will also need to go and find the Message-ID of your previous cover letter.\n+You will also need to go and find the Message-ID of your original cover letter.\n You can either note it when you send the first series, from the output of `git\n send-email`, or you can look it up on the\n https://lore.kernel.org/git[mailing list]. Find your cover letter in the\n"},{"id":"544600","messageId":"aiACDLOtd_0_CCD7@wyuan.org","threadId":"65738","inReplyTo":"20260603-pks-b4-v2-1-a8aea0aa2c23@pks.im","subject":"Re: [PATCH v2 1/3] Documentation/MyFirstContribution: recommend shallow threading","fromName":"Weijie Yuan","fromEmail":"wy@wyuan.org","sentAt":"2026-06-03T10:29:32Z","receivedAt":"2026-06-03T10:29:42Z","isPatch":true,"body":"I'm afraid there will be some chaos.\n\nAs mentioned earlier, GitGitGadget now supports deep nesting of\niterations, if b4 changes while GitGitGadget doesn't, it would be\ninconsistent in the archive. So, negotiation is necessary here.\n\nAs I know, b4 can generate a cover letter containing \"Changes with vn\",\ne.g. in [PATCH v5 00/10], there would be Changes with v4, v3, v2, v1. In\nthis case, it is semantically correct that the cover letter of v5 is\nreplying-to the cover letter of v1.\n\nBut in traditional way, it seems that the norm is put a range-diff in\nthe cover letter. In this case, chain-reply-to makes more sence to me:\ne.g. The cover letter contains the range-diff against v2, so cover\nletter v3 is pointing to cover letter v2. (I don't know whether\ngit format-patch accepts several --range-diff or not, but if so, I\nguess it might be painful to typing several refs, or copy and paste\nfrom previous cover letter) Therefore, if git format-patch could\ngenerate cover letter containing all the changes with v4/v3/v2/v1 as b4\ndoes, it would be consistent, and semantically correct to pointing to\nthe first cover letter.\n\nDo we need to consider backward compatibility here? ;-)\n\nThanks!\n"},{"id":"544601","messageId":"aiAK9eLvew+mgWt+@szeder.dev","threadId":"65738","inReplyTo":"ah_PyDwO1Sffr5yq@pks.im","subject":"Re: [PATCH 1/2] b4: introduce configuration for the Git project","fromName":"SZEDER Gábor","fromEmail":"szeder.dev@gmail.com","sentAt":"2026-06-03T11:07:33Z","receivedAt":"2026-06-03T11:07:48Z","isPatch":true,"body":"On Wed, Jun 03, 2026 at 08:55:04AM +0200, Patrick Steinhardt wrote:\n> On Wed, Jun 03, 2026 at 10:12:22AM +0800, Weijie Yuan wrote:\n> > On Tue, Jun 02, 2026 at 08:09:55PM +0300, Tuomas Ahola wrote:\n> > > Huh? Doesn't MyFirstContribution speak *against* shallow threading?\n> > >\n> > > \t [...] make sure to replace it with the correct Message-ID for your\n> > > \t**previous cover letter** - that is, if you're sending v2, use the Message-ID\n> > > \tfrom v1; if you're sending v3, use the Message-ID from v2.\n> > \n> > I don't get it. Doesn't shallow threading means every following patches\n> > are replying to the cover letter? Replying to the previous one is\n> > --chain-reply-to, if I'm not mistaken.\n> \n> Shallow threading basically means that all patches are sent as a\n> response to the current cover letter, and the current cover letter is\n> always attached to the cover letter of the _first_ version.\n\nNo, in Git shallow threading means that all patches are sent as a\nrespose to the current cover letter, period. It has nothing to do\nwith whether the current cover letter is sent as a reply to the cover\nletter of the first or the previous version.\n\n> So this quote is definitely at odds with the configuration I have\n> proposed. It's actually quite surprising to me that we recommend deep\n> threading -- I personally find it extremely hard to navigate as the\n> nesting eventually gets way too deep.\n\nDeep threading means that every mail is a reply to the previous one.\nAgain, it has nothing to do with the relation of the current cover\nletter and the previous cover letters.\n\nTherefore, we do not recommend deep threading.\n\n> You know -- I'll include a patch that changes the wording there to also\n> use shallow nesting, mostly to kick off a discussion and arrive at a\n> decision there.\n\n\n"},{"id":"544606","messageId":"aiAcv_p4bR1pNImf@wyuan.org","threadId":"65738","inReplyTo":"aiAK9eLvew+mgWt+@szeder.dev","subject":"Re: [PATCH 1/2] b4: introduce configuration for the Git project","fromName":"Weijie Yuan","fromEmail":"wy@wyuan.org","sentAt":"2026-06-03T12:23:27Z","receivedAt":"2026-06-03T12:23:44Z","isPatch":true,"body":"On Wed, Jun 03, 2026 at 01:07:33PM +0200, SZEDER Gábor wrote:\n> No, in Git shallow threading means that all patches are sent as a\n> respose to the current cover letter, period. It has nothing to do\n> with whether the current cover letter is sent as a reply to the cover\n> letter of the first or the previous version.\n\nThanks, agree\n\n> Deep threading means that every mail is a reply to the previous one.\n> Again, it has nothing to do with the relation of the current cover\n> letter and the previous cover letters.\n>\n> Therefore, we do not recommend deep threading.\n\nSo the same reason with Patrick?\n\nThanks\n"},{"id":"544616","messageId":"20260603133017.XkcQR%taahol@utu.fi","threadId":"65738","inReplyTo":"aiAK9eLvew+mgWt+@szeder.dev","subject":"Re: [PATCH 1/2] b4: introduce configuration for the Git project","fromName":"Tuomas Ahola","fromEmail":"taahol@utu.fi","sentAt":"2026-06-03T13:30:17Z","receivedAt":"2026-06-03T13:30:27Z","isPatch":true,"body":"SZEDER Gábor wrote:\n> On Wed, Jun 03, 2026 at 08:55:04AM +0200, Patrick Steinhardt wrote:\n> > On Wed, Jun 03, 2026 at 10:12:22AM +0800, Weijie Yuan wrote:\n> > > On Tue, Jun 02, 2026 at 08:09:55PM +0300, Tuomas Ahola wrote:\n> > > > Huh? Doesn't MyFirstContribution speak *against* shallow threading?\n> > > >\n> > > > \t [...] make sure to replace it with the correct Message-ID for your\n> > > > \t**previous cover letter** - that is, if you're sending v2, use the Message-ID\n> > > > \tfrom v1; if you're sending v3, use the Message-ID from v2.\n> > > \n> > > I don't get it. Doesn't shallow threading means every following patches\n> > > are replying to the cover letter? Replying to the previous one is\n> > > --chain-reply-to, if I'm not mistaken.\n> > \n> > Shallow threading basically means that all patches are sent as a\n> > response to the current cover letter, and the current cover letter is\n> > always attached to the cover letter of the _first_ version.\n> \n> No, in Git shallow threading means that all patches are sent as a\n> respose to the current cover letter, period. It has nothing to do\n> with whether the current cover letter is sent as a reply to the cover\n> letter of the first or the previous version.\n> \n\nThat seems to be the established meaning of shallow threading, e.g. in\n`git format-patch --thread=shallow`. Unfortunately there is a slight\nterminology clash here.\n\nIndeed, in B4 the config option `b4.send-same-thread = shallow` *is*\nabout whether the cover letter is a reply to v1 or v(n-1).\n\n> > So this quote is definitely at odds with the configuration I have\n> > proposed. It's actually quite surprising to me that we recommend deep\n> > threading -- I personally find it extremely hard to navigate as the\n> > nesting eventually gets way too deep.\n> \n> Deep threading means that every mail is a reply to the previous one.\n> Again, it has nothing to do with the relation of the current cover\n> letter and the previous cover letters.\n> \n> Therefore, we do not recommend deep threading.\n> \n\nIn the usual meaning of the word that is the case. Most certainly\nwe don't recommend that kind of deep threading, but that wasn't the\nquestion we were discussing here.\n"},{"id":"544618","messageId":"87qzmn20a9.fsf@emacs.iotcl.com","threadId":"65738","inReplyTo":"20260603-pks-b4-v2-3-a8aea0aa2c23@pks.im","subject":"Re: [PATCH v2 3/3] b4: introduce configuration for the Git project","fromName":"Toon Claes","fromEmail":"toon@iotcl.com","sentAt":"2026-06-03T13:58:38Z","receivedAt":"2026-06-03T13:59:11Z","isPatch":true,"body":"Patrick Steinhardt writes:\n\n> We're about to extend our documentation to recommend b4 for sending\n> patch series to the mailing list. Prepare for this by introducing a b4\n> configuration so that the tool knows to honor our preferences. For now,\n> this configuration does two things:\n>\n> - It configures \"send-same-thread = shallow\", which tells b4 to always\n> send subsequent versions of the same patch series as a reply to the\n> cover letter of the first version.\n>\n> - It configures \"prep-cover-template\", which tells b4 to use a custom\n> template for the cover letter. The most important change compared to\n> the default template is that our custom template also includes a\n> range-diff.\n>\n> There's potentially more things that we may want to configure going\n> forward, like for example auto-configuration of folks to Cc on certain\n> patches. But these two tweaks feel like a good place to start.\n>\n> Note that these values only serve as defaults, and users may want to\n> tweak those defaults based on their own preference. Luckily, users can\n> do that without having to touch `.b4-config` at all, as b4 allows them\n> to override values via Git configuration:\n>\n> ```\n> $ git config set b4.prep-cover-template /does/not/exist\n> $ b4 send --dry-run\n> ERROR: prep-cover-template says to use x, but it does not exist\n> ```\n>\n> So this gives users an easy way to override our defaults without having\n> to touch \".b4-config\", which would dirty the tree.\n>\n> Signed-off-by: Patrick Steinhardt \n> ---\n> .b4-config | 6 ++++++\n> .b4-cover-template | 11 +++++++++++\n> 2 files changed, 17 insertions(+)\n>\n> diff --git a/.b4-config b/.b4-config\n> new file mode 100644\n> index 0000000000..fd4fb56b6d\n> --- /dev/null\n> +++ b/.b4-config\n> @@ -0,0 +1,6 @@\n> +# Note that these are default values that you can tweak via the typical\n> +# git-config(1) machinery. You thus shouldn't ever have to change this file.\n> +# See also https://b4.docs.kernel.org/en/latest/config.html.\n> +[b4]\n> +send-same-thread = shallow\n\nIs it worth to note this requires v0.15 or higher?\n\nThat version was released only 2 months ago, I can imagine many distros\nstill ship an older version, what happens if a version doesn't support\nthis setting yet?\n\n> +prep-cover-template = ./.b4-cover-template\n> diff --git a/.b4-cover-template b/.b4-cover-template\n> new file mode 100644\n> index 0000000000..ab864933b5\n> --- /dev/null\n> +++ b/.b4-cover-template\n> @@ -0,0 +1,11 @@\n> +${cover}\n> +\n> +---\n> +${shortlog}\n> +\n> +${diffstat}\n> +\n> +${range_diff}\n> +---\n> +base-commit: ${base_commit}\n> +${prerequisites}\n>\n> -- \n> 2.54.0.1064.gd145956f57.dirty\n>\n>\n\n-- \nCheers,\nToon\n"},{"id":"544644","messageId":"f1dbb848-2d9b-488a-835b-2d23006b5fa6@app.fastmail.com","threadId":"65738","inReplyTo":"20260603-pks-b4-v2-1-a8aea0aa2c23@pks.im","subject":"Re: [PATCH v2 1/3] Documentation/MyFirstContribution: recommend shallow threading","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-06-03T20:09:39Z","receivedAt":"2026-06-03T20:10:01Z","isPatch":true,"body":"On Wed, Jun 3, 2026, at 08:58, Patrick Steinhardt wrote:\n> The \"MyFirstContribution\" document recommends the use of deep threading:\n> every cover letter of subsequent iterations shall be linked to the cover\n> letter of the preceding version. The result of this is that eventually,\n> threads with many versions are getting nested so deep that it becomes\n> hard to follow.\n>\n> Adapt the recommendation to instead propose shallow threading: instead\n> of linking the cover letter to the previous cover letter, the user is\n> supposed to always link it to the first cover letter. This still makes\n> it easy to follow the iterations, but has the benefit of nesting to a\n> much shallower level.\n>\n> Signed-off-by: Patrick Steinhardt \n> ---\n> Documentation/MyFirstContribution.adoc | 4 ++--\n> 1 file changed, 2 insertions(+), 2 deletions(-)\n>[snip]\n\nOnly today did I notice that your eleven-version git-history(1) series\nuses this style. (Or: today I noticed that it’a thing)\n\nhttps://lore.kernel.org/git/20250819-b4-pks-history-builtin-v1-0-9b77c32688fe@pks.im/\n\nThat would have had a bad rightward drift with the usual reply to\nprevious version style.\n\nI’ve been reading Lore on Safari on mobile and some threads go so deep\nthat the replies just become unclickable backticks. *Huh?* Well I can\nuse the Next/Previous buttons and maybe there is a way to make it work,\nbut I’ve just given up on those right-going subthreads. ;)\n\n... and I also don’t see any drawbacks to that threading, using that\nseries as an example. It looks just as comprehensible as the usual\nstyle.\n"},{"id":"544655","messageId":"xmqqmrxbp0s6.fsf@gitster.g","threadId":"65738","inReplyTo":"aiAK9eLvew+mgWt+@szeder.dev","subject":"Re: [PATCH 1/2] b4: introduce configuration for the Git project","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-06-04T01:11:37Z","receivedAt":"2026-06-04T01:11:40Z","isPatch":true,"body":"SZEDER Gábor writes:\n\n> No, in Git shallow threading means that all patches are sent as a\n> respose to the current cover letter, period. It has nothing to do\n> with whether the current cover letter is sent as a reply to the cover\n> letter of the first or the previous version.\n> ...\n> Deep threading means that every mail is a reply to the previous one.\n> Again, it has nothing to do with the relation of the current cover\n> letter and the previous cover letters.\n>\n> Therefore, we do not recommend deep threading.\n\nThe above exactly matches my understanding of the current best\npractice. Inside an iteration of a series, we want a cover letter\nwith everybody else responding to it. We do not have a word to\ndescribe how the latest iteration refers to its previous iteration\nvia In-reply-to: or References: headers, but our preference is to\nmake the cover letter of iteration N+1 to be a response to the cover\nletter of iteration N.\n\nFor a single-patch topic (without a cover letter) with multiple\niterations, each iteration would be response to its previous\niteration, which may make it look like \"deep threading\", but as you\npointed out, the \"deep threading\" concept does not go across\niterations.\n\nHaving said that, I've seen a cover letter of iteration N (for any\nvalue of N > 1) that respondes to the cover letter of the initial\niteration. While it seems not to break \"br\" and the lore archive\ndoes not seem unhappy about it, I am not sure if tooling used by\nother people are also happy with it.\n\nThanks.\n"},{"id":"544660","messageId":"87mrxa27xq.fsf@emacs.iotcl.com","threadId":"65738","inReplyTo":"20260603-pks-b4-v2-2-a8aea0aa2c23@pks.im","subject":"Re: [PATCH v2 2/3] Documentation/MyFirstContribution: recommend the use of b4","fromName":"Toon Claes","fromEmail":"toon@iotcl.com","sentAt":"2026-06-04T05:25:37Z","receivedAt":"2026-06-04T05:25:43Z","isPatch":true,"body":"Patrick Steinhardt writes:\n\n> The b4 tool originates from the Linux kernel community and is intended\n> to help mailing-list based workflows. It automates a lot of the annoying\n> bookkeeping tasks that contributors typically need to do: tracking the\n> list of recipients, Message-IDs, range-diffs and the like. In addition\n> to that, b4 also has many other subcommands that help the maintainer and\n> reviewers.\n>\n> The Git project uses the same infrastructure as the kernel, so this tool\n> is also a very good fit for us. Adapt \"MyFirstContribution\" to\n> explicitly recommend its use.\n>\n> Signed-off-by: Patrick Steinhardt \n> ---\n> Documentation/MyFirstContribution.adoc | 92 ++++++++++++++++++++++++++++++++--\n> Documentation/SubmittingPatches | 6 ++-\n> 2 files changed, 93 insertions(+), 5 deletions(-)\n>\n> diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc\n> index 069020196c..fc0b06ae67 100644\n> --- a/Documentation/MyFirstContribution.adoc\n> +++ b/Documentation/MyFirstContribution.adoc\n> @@ -833,7 +833,7 @@ This patchset is part of the MyFirstContribution tutorial and should not\n> be merged.\n> ----\n> \n> -At this point the tutorial diverges, in order to demonstrate two\n> +At this point the tutorial diverges, in order to demonstrate three\n> different methods of formatting your patchset and getting it reviewed.\n> \n> The first method to be covered is GitGitGadget, which is useful for those\n> @@ -845,9 +845,14 @@ more fine-grained control over the emails to be sent. This method requires some\n> setup which can change depending on your system and will not be covered in this\n> tutorial.\n> \n> +The third method to be covered is `b4`, which builds on top of `git\n> +format-patch` and `git send-email`. This method is the recommended way to\n> +submit patches via mail as it automates a lot of the bookkeeping required by\n> +`git send-email`.\n\nThe GitGitGadget method includes Running CI, maybe that's worth\nmentioning the user is responsible themselves to run the whole test\nsuite? Or is this outside the scope of this series, since `git\nsend-email` doesn't include that too.\n\n-- \nCheers,\nToon\n"},{"id":"544862","messageId":"aiZltnUUt2Z_6VR-@pks.im","threadId":"65738","inReplyTo":"20260603100145.7iym5%taahol@utu.fi","subject":"Re: [PATCH v2 1/3] Documentation/MyFirstContribution: recommend shallow threading","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-06-08T06:48:22Z","receivedAt":"2026-06-08T06:48:29Z","isPatch":true,"body":"On Wed, Jun 03, 2026 at 01:01:45PM +0300, Tuomas Ahola wrote:\n> Patrick Steinhardt wrote:\n> \n> > The \"MyFirstContribution\" document recommends the use of deep threading:\n> > every cover letter of subsequent iterations shall be linked to the cover\n> > letter of the preceding version. The result of this is that eventually,\n> > threads with many versions are getting nested so deep that it becomes\n> > hard to follow.\n> > \n> > Adapt the recommendation to instead propose shallow threading: instead\n> > of linking the cover letter to the previous cover letter, the user is\n> > supposed to always link it to the first cover letter. This still makes\n> > it easy to follow the iterations, but has the benefit of nesting to a\n> > much shallower level.\n> > \n> > Signed-off-by: Patrick Steinhardt \n> > ---\n> > Documentation/MyFirstContribution.adoc | 4 ++--\n> > 1 file changed, 2 insertions(+), 2 deletions(-)\n> > \n> > diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc\n> > index b9fdefce02..069020196c 100644\n> > --- a/Documentation/MyFirstContribution.adoc\n> > +++ b/Documentation/MyFirstContribution.adoc\n> > @@ -1227,8 +1227,8 @@ Message-ID: \n> > \n> > Your Message-ID is ``. This example will be used\n> > below as well; make sure to replace it with the correct Message-ID for your\n> > -**previous cover letter** - that is, if you're sending v2, use the Message-ID\n> > -from v1; if you're sending v3, use the Message-ID from v2.\n> > +**first cover letter** - that is, for any subsequent version that you send,\n> > +always use the Message-ID from v1.\n> > \n> > While you're looking at the email, you should also note who is CC'd, as it's\n> > common practice in the mailing list to keep all CCs on a thread. You can add\n> > \n> > -- \n> > 2.54.0.1064.gd145956f57.dirty\n> \n> If we adapt this change to the guidance, let's fix also other places of the\n> document that talk about replying to the previous cover letter.\n\nGood catch, thanks!\n\nPatrick\n"},{"id":"544863","messageId":"aiZlu36Fh020L1Ip@pks.im","threadId":"65738","inReplyTo":"aiACDLOtd_0_CCD7@wyuan.org","subject":"Re: [PATCH v2 1/3] Documentation/MyFirstContribution: recommend shallow threading","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-06-08T06:48:27Z","receivedAt":"2026-06-08T06:48:32Z","isPatch":true,"body":"On Wed, Jun 03, 2026 at 06:29:32PM +0800, Weijie Yuan wrote:\n> I'm afraid there will be some chaos.\n\nI think \"chaos\" is a bit exaggerated. We already have both styles on the\nmailing list, and I think in general people are able to cope with that\njust fine. :)\n\n> As mentioned earlier, GitGitGadget now supports deep nesting of\n> iterations, if b4 changes while GitGitGadget doesn't, it would be\n> inconsistent in the archive. So, negotiation is necessary here.\n\nThat's a good point though -- if we change the recommendation, we should\naim to change it consistently. I'll talk with Dscho (maintainer of GGG)\ntoday.\n\nThanks!\n\nPatrick\n"},{"id":"544864","messageId":"aiZlwi0V4jrtSRAj@pks.im","threadId":"65738","inReplyTo":"f1dbb848-2d9b-488a-835b-2d23006b5fa6@app.fastmail.com","subject":"Re: [PATCH v2 1/3] Documentation/MyFirstContribution: recommend shallow threading","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-06-08T06:48:34Z","receivedAt":"2026-06-08T06:48:39Z","isPatch":true,"body":"On Wed, Jun 03, 2026 at 10:09:39PM +0200, Kristoffer Haugsbakk wrote:\n> On Wed, Jun 3, 2026, at 08:58, Patrick Steinhardt wrote:\n> > The \"MyFirstContribution\" document recommends the use of deep threading:\n> > every cover letter of subsequent iterations shall be linked to the cover\n> > letter of the preceding version. The result of this is that eventually,\n> > threads with many versions are getting nested so deep that it becomes\n> > hard to follow.\n> >\n> > Adapt the recommendation to instead propose shallow threading: instead\n> > of linking the cover letter to the previous cover letter, the user is\n> > supposed to always link it to the first cover letter. This still makes\n> > it easy to follow the iterations, but has the benefit of nesting to a\n> > much shallower level.\n> >\n> > Signed-off-by: Patrick Steinhardt \n> > ---\n> > Documentation/MyFirstContribution.adoc | 4 ++--\n> > 1 file changed, 2 insertions(+), 2 deletions(-)\n> >[snip]\n> \n> Only today did I notice that your eleven-version git-history(1) series\n> uses this style. (Or: today I noticed that it’a thing)\n> \n> https://lore.kernel.org/git/20250819-b4-pks-history-builtin-v1-0-9b77c32688fe@pks.im/\n> \n> That would have had a bad rightward drift with the usual reply to\n> previous version style.\n> \n> I’ve been reading Lore on Safari on mobile and some threads go so deep\n> that the replies just become unclickable backticks. *Huh?* Well I can\n> use the Next/Previous buttons and maybe there is a way to make it work,\n> but I’ve just given up on those right-going subthreads. ;)\n> \n> ... and I also don’t see any drawbacks to that threading, using that\n> series as an example. It looks just as comprehensible as the usual\n> style.\n\nYeah. It doesn't matter much for patch series that don't require many\niterations. But eventually I feel like it gets out-of-hand to have the\ndeep nesting.\n\nPatrick\n"},{"id":"544865","messageId":"aiZlx-ue6N8gCIMr@pks.im","threadId":"65738","inReplyTo":"87mrxa27xq.fsf@emacs.iotcl.com","subject":"Re: [PATCH v2 2/3] Documentation/MyFirstContribution: recommend the use of b4","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-06-08T06:48:39Z","receivedAt":"2026-06-08T06:48:44Z","isPatch":true,"body":"On Thu, Jun 04, 2026 at 07:25:37AM +0200, Toon Claes wrote:\n> Patrick Steinhardt writes:\n> > diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc\n> > index 069020196c..fc0b06ae67 100644\n> > --- a/Documentation/MyFirstContribution.adoc\n> > +++ b/Documentation/MyFirstContribution.adoc\n> > @@ -833,7 +833,7 @@ This patchset is part of the MyFirstContribution tutorial and should not\n> > be merged.\n> > ----\n> > \n> > -At this point the tutorial diverges, in order to demonstrate two\n> > +At this point the tutorial diverges, in order to demonstrate three\n> > different methods of formatting your patchset and getting it reviewed.\n> > \n> > The first method to be covered is GitGitGadget, which is useful for those\n> > @@ -845,9 +845,14 @@ more fine-grained control over the emails to be sent. This method requires some\n> > setup which can change depending on your system and will not be covered in this\n> > tutorial.\n> > \n> > +The third method to be covered is `b4`, which builds on top of `git\n> > +format-patch` and `git send-email`. This method is the recommended way to\n> > +submit patches via mail as it automates a lot of the bookkeeping required by\n> > +`git send-email`.\n> \n> The GitGitGadget method includes Running CI, maybe that's worth\n> mentioning the user is responsible themselves to run the whole test\n> suite? Or is this outside the scope of this series, since `git\n> send-email` doesn't include that too.\n\nI'd say it's out-of-scope for this patch series.\n\nThat being said, I have been wondering last week whether we can automate\nrunning CI in some fashion to shorten feedback cycles, bridge the gap\nbetween the mailing list and CI and ultimately help both reviewers and\nJunio. Some subsystems in the Linux kernel for example have tooling that\npicks up patch series from the mailing list, runs it through CI and then\nreports results to the mailing list (for example [1]).\n\nHaving something like that might be valuable for us, too.\n\nPatrick\n\n[1]: https://github.com/linux-netdev/nipa\n"},{"id":"544866","messageId":"aiZlzBEB_AnQ4mVK@pks.im","threadId":"65738","inReplyTo":"aiAK9eLvew+mgWt+@szeder.dev","subject":"Re: [PATCH 1/2] b4: introduce configuration for the Git project","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-06-08T06:48:44Z","receivedAt":"2026-06-08T06:48:49Z","isPatch":true,"body":"On Wed, Jun 03, 2026 at 01:07:33PM +0200, SZEDER Gábor wrote:\n> On Wed, Jun 03, 2026 at 08:55:04AM +0200, Patrick Steinhardt wrote:\n> > On Wed, Jun 03, 2026 at 10:12:22AM +0800, Weijie Yuan wrote:\n> > > On Tue, Jun 02, 2026 at 08:09:55PM +0300, Tuomas Ahola wrote:\n> > > > Huh? Doesn't MyFirstContribution speak *against* shallow threading?\n> > > >\n> > > > \t [...] make sure to replace it with the correct Message-ID for your\n> > > > \t**previous cover letter** - that is, if you're sending v2, use the Message-ID\n> > > > \tfrom v1; if you're sending v3, use the Message-ID from v2.\n> > > \n> > > I don't get it. Doesn't shallow threading means every following patches\n> > > are replying to the cover letter? Replying to the previous one is\n> > > --chain-reply-to, if I'm not mistaken.\n> > \n> > Shallow threading basically means that all patches are sent as a\n> > response to the current cover letter, and the current cover letter is\n> > always attached to the cover letter of the _first_ version.\n> \n> No, in Git shallow threading means that all patches are sent as a\n> respose to the current cover letter, period. It has nothing to do\n> with whether the current cover letter is sent as a reply to the cover\n> letter of the first or the previous version.\n> \n> > So this quote is definitely at odds with the configuration I have\n> > proposed. It's actually quite surprising to me that we recommend deep\n> > threading -- I personally find it extremely hard to navigate as the\n> > nesting eventually gets way too deep.\n> \n> Deep threading means that every mail is a reply to the previous one.\n> Again, it has nothing to do with the relation of the current cover\n> letter and the previous cover letters.\n> \n> Therefore, we do not recommend deep threading.\n\nOh, you're right of course. I totally forgot that we even had this\nstyle.\n\nPatrick\n"},{"id":"544867","messageId":"aiZl0ce7lnRrL4bv@pks.im","threadId":"65738","inReplyTo":"xmqqmrxbp0s6.fsf@gitster.g","subject":"Re: [PATCH 1/2] b4: introduce configuration for the Git project","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-06-08T06:48:49Z","receivedAt":"2026-06-08T06:48:54Z","isPatch":true,"body":"On Thu, Jun 04, 2026 at 10:11:37AM +0900, Junio C Hamano wrote:\n> Having said that, I've seen a cover letter of iteration N (for any\n> value of N > 1) that respondes to the cover letter of the initial\n> iteration. While it seems not to break \"br\" and the lore archive\n> does not seem unhappy about it, I am not sure if tooling used by\n> other people are also happy with it.\n\nYeah, I always use that style myself. I mostly prefer it because the\nnesting for long-running patch series with many versions is eventually\ngetting out of hand and hard to navigate, and I haven't seen any tooling\nbreaking as a result of that style.\n\nIf I'm the only one who thinks that style to be preferable I am happy to\nadapt. I'm not really sure yet what the consensus is -- I'll send one\nmore version that includes the changes, but if we continue to be split\nor in favor of the current status quo I'll drop those in the next\nversion.\n\nThanks!\n\nPatrick\n"},{"id":"544868","messageId":"aiZl1ZDnX0KvWxW1@pks.im","threadId":"65738","inReplyTo":"87qzmn20a9.fsf@emacs.iotcl.com","subject":"Re: [PATCH v2 3/3] b4: introduce configuration for the Git project","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-06-08T06:48:53Z","receivedAt":"2026-06-08T06:48:58Z","isPatch":true,"body":"On Wed, Jun 03, 2026 at 03:58:38PM +0200, Toon Claes wrote:\n> Patrick Steinhardt writes:\n> > diff --git a/.b4-config b/.b4-config\n> > new file mode 100644\n> > index 0000000000..fd4fb56b6d\n> > --- /dev/null\n> > +++ b/.b4-config\n> > @@ -0,0 +1,6 @@\n> > +# Note that these are default values that you can tweak via the typical\n> > +# git-config(1) machinery. You thus shouldn't ever have to change this file.\n> > +# See also https://b4.docs.kernel.org/en/latest/config.html.\n> > +[b4]\n> > +send-same-thread = shallow\n> \n> Is it worth to note this requires v0.15 or higher?\n> \n> That version was released only 2 months ago, I can imagine many distros\n> still ship an older version, what happens if a version doesn't support\n> this setting yet?\n\nThat's fair. In case it's not supported we fall back to the default,\nwhich is to not use threading at all.\n\nMight be another indicator that we should just stick with the current\nthreading style.\n\nPatrick\n"},{"id":"544869","messageId":"20260608-pks-b4-v3-0-f5e497d10c56@pks.im","threadId":"65738","inReplyTo":"20260602-pks-b4-v1-0-a7ae5a49e9cf@pks.im","subject":"[PATCH v3 0/3] Documentation: recommend the use of b4","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-06-08T06:49:52Z","receivedAt":"2026-06-08T06:50:01Z","isPatch":true,"body":"Hi,\n\nthis small patch series wires up b4 in Git and recommends the use\nthereof via \"MyFirstContribution\", as discussed in [1].\n\nChanges in v3:\n - I wasn't really able to judge consensus one way or the other\n regarding the deep vs shallow nesting of cover letters, so I still\n have the change to shallow nesting of cover letters part of this\n series. If we continue to be split on this one (or if we favor the\n current status quo) I'm happy to drop the first patch and adapt the\n last patch to use deep nesting of cover letters instead.\n - Hopefully fix some confusion by saying \"shallow/deep threading of\n cover letters\".\n - Fix some more instances where we recommend deep threading of cover\n letters.\n - Link to v2: https://patch.msgid.link/20260603-pks-b4-v2-0-a8aea0aa2c23@pks.im\n\nChanges in v2:\n - Reorder commits so that the b4 docs are added first.\n - Add a section that highlights how to configure b4, and that points\n out that the per-project defaults can be overridden via Git\n configuration.\n - Add a patch to MyFirstContribution that recommends shallow\n threading. I mostly intend this to be a discussion starter so that\n the `.b4-config` file matches our preferred threading style.\n - Fix a typo.\n - Link to v1: https://patch.msgid.link/20260602-pks-b4-v1-0-a7ae5a49e9cf@pks.im\n\nThanks!\n\nPatrick\n\n[1]: \n\n---\nPatrick Steinhardt (3):\n MyFirstContribution: recommend shallow threading of cover letters\n MyFirstContribution: recommend the use of b4\n b4: introduce configuration for the Git project\n\n .b4-config | 6 ++\n .b4-cover-template | 11 ++++\n Documentation/MyFirstContribution.adoc | 100 ++++++++++++++++++++++++++++++---\n Documentation/SubmittingPatches | 6 +-\n 4 files changed, 114 insertions(+), 9 deletions(-)\n\nRange-diff versus v2:\n\n1: f7784c8f7f ! 1: 4b0c4f9aca Documentation/MyFirstContribution: recommend shallow threading\n @@ Metadata\n Author: Patrick Steinhardt \n \n ## Commit message ##\n - Documentation/MyFirstContribution: recommend shallow threading\n + MyFirstContribution: recommend shallow threading of cover letters\n \n - The \"MyFirstContribution\" document recommends the use of deep threading:\n - every cover letter of subsequent iterations shall be linked to the cover\n - letter of the preceding version. The result of this is that eventually,\n - threads with many versions are getting nested so deep that it becomes\n - hard to follow.\n + The \"MyFirstContribution\" document recommends the use of deep threading\n + of cover letters: every cover letter of subsequent iterations shall be\n + linked to the cover letter of the preceding version. The result of this\n + is that eventually, threads with many versions are getting nested so\n + deep that it becomes hard to follow.\n \n - Adapt the recommendation to instead propose shallow threading: instead\n - of linking the cover letter to the previous cover letter, the user is\n - supposed to always link it to the first cover letter. This still makes\n - it easy to follow the iterations, but has the benefit of nesting to a\n - much shallower level.\n + Adapt the recommendation to instead propose shallow threading of cover\n + letters: instead of linking the cover letter to the previous cover\n + letter, the user is supposed to always link it to the first cover\n + letter. This still makes it easy to follow the iterations, but has the\n + benefit of nesting to a much shallower level.\n \n Signed-off-by: Patrick Steinhardt \n \n ## Documentation/MyFirstContribution.adoc ##\n +@@ Documentation/MyFirstContribution.adoc: We can note a few things:\n + v3\", etc. in place of \"PATCH\". For example, \"[PATCH v2 1/3]\" would be the first of\n + three patches in the second iteration. Each iteration is sent with a new cover\n + letter (like \"[PATCH v2 0/3]\" above), itself a reply to the cover letter of the\n +- previous iteration (more on that below).\n ++ first iteration (more on that below).\n + \n + NOTE: A single-patch topic is sent with \"[PATCH]\", \"[PATCH v2]\", etc. without\n + _i_/_n_ numbering (in the above thread overview, no single-patch topic appears,\n +@@ Documentation/MyFirstContribution.adoc: between your last version and now, if it's something significant. You do not\n + need the exact same body in your second cover letter; focus on explaining to\n + reviewers the changes you've made that may not be as visible.\n + \n +-You will also need to go and find the Message-ID of your previous cover letter.\n ++You will also need to go and find the Message-ID of your first cover letter.\n + You can either note it when you send the first series, from the output of `git\n + send-email`, or you can look it up on the\n + https://lore.kernel.org/git[mailing list]. Find your cover letter in the\n @@ Documentation/MyFirstContribution.adoc: Message-ID: \n \n Your Message-ID is ``. This example will be used\n2: e8f3caf73a ! 2: 625de75a33 Documentation/MyFirstContribution: recommend the use of b4\n @@ Metadata\n Author: Patrick Steinhardt \n \n ## Commit message ##\n - Documentation/MyFirstContribution: recommend the use of b4\n + MyFirstContribution: recommend the use of b4\n \n The b4 tool originates from the Linux kernel community and is intended\n to help mailing-list based workflows. It automates a lot of the annoying\n3: 35591c55c8 = 3: a95973cfb6 b4: introduce configuration for the Git project\n\n---\nbase-commit: 9ac3f193c05c2237e2b14ebaa1149e9fc8a1abe0\nchange-id: 20260602-pks-b4-31cc20d7f84b\n\n"},{"id":"544870","messageId":"20260608-pks-b4-v3-1-f5e497d10c56@pks.im","threadId":"65738","inReplyTo":"20260608-pks-b4-v3-0-f5e497d10c56@pks.im","subject":"[PATCH v3 1/3] MyFirstContribution: recommend shallow threading of cover letters","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-06-08T06:49:53Z","receivedAt":"2026-06-08T06:50:06Z","isPatch":true,"body":"The \"MyFirstContribution\" document recommends the use of deep threading\nof cover letters: every cover letter of subsequent iterations shall be\nlinked to the cover letter of the preceding version. The result of this\nis that eventually, threads with many versions are getting nested so\ndeep that it becomes hard to follow.\n\nAdapt the recommendation to instead propose shallow threading of cover\nletters: instead of linking the cover letter to the previous cover\nletter, the user is supposed to always link it to the first cover\nletter. This still makes it easy to follow the iterations, but has the\nbenefit of nesting to a much shallower level.\n\nSigned-off-by: Patrick Steinhardt \n---\n Documentation/MyFirstContribution.adoc | 8 ++++----\n 1 file changed, 4 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc\nindex b9fdefce02..984b7f5aa8 100644\n--- a/Documentation/MyFirstContribution.adoc\n+++ b/Documentation/MyFirstContribution.adoc\n@@ -790,7 +790,7 @@ We can note a few things:\n v3\", etc. in place of \"PATCH\". For example, \"[PATCH v2 1/3]\" would be the first of\n three patches in the second iteration. Each iteration is sent with a new cover\n letter (like \"[PATCH v2 0/3]\" above), itself a reply to the cover letter of the\n- previous iteration (more on that below).\n+ first iteration (more on that below).\n \n NOTE: A single-patch topic is sent with \"[PATCH]\", \"[PATCH v2]\", etc. without\n _i_/_n_ numbering (in the above thread overview, no single-patch topic appears,\n@@ -1214,7 +1214,7 @@ between your last version and now, if it's something significant. You do not\n need the exact same body in your second cover letter; focus on explaining to\n reviewers the changes you've made that may not be as visible.\n \n-You will also need to go and find the Message-ID of your previous cover letter.\n+You will also need to go and find the Message-ID of your first cover letter.\n You can either note it when you send the first series, from the output of `git\n send-email`, or you can look it up on the\n https://lore.kernel.org/git[mailing list]. Find your cover letter in the\n@@ -1227,8 +1227,8 @@ Message-ID: \n \n Your Message-ID is ``. This example will be used\n below as well; make sure to replace it with the correct Message-ID for your\n-**previous cover letter** - that is, if you're sending v2, use the Message-ID\n-from v1; if you're sending v3, use the Message-ID from v2.\n+**first cover letter** - that is, for any subsequent version that you send,\n+always use the Message-ID from v1.\n \n While you're looking at the email, you should also note who is CC'd, as it's\n common practice in the mailing list to keep all CCs on a thread. You can add\n\n-- \n2.54.0.1136.gdb2ca164c4.dirty\n\n"},{"id":"544871","messageId":"20260608-pks-b4-v3-2-f5e497d10c56@pks.im","threadId":"65738","inReplyTo":"20260608-pks-b4-v3-0-f5e497d10c56@pks.im","subject":"[PATCH v3 2/3] MyFirstContribution: recommend the use of b4","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-06-08T06:49:54Z","receivedAt":"2026-06-08T06:50:08Z","isPatch":true,"body":"The b4 tool originates from the Linux kernel community and is intended\nto help mailing-list based workflows. It automates a lot of the annoying\nbookkeeping tasks that contributors typically need to do: tracking the\nlist of recipients, Message-IDs, range-diffs and the like. In addition\nto that, b4 also has many other subcommands that help the maintainer and\nreviewers.\n\nThe Git project uses the same infrastructure as the kernel, so this tool\nis also a very good fit for us. Adapt \"MyFirstContribution\" to\nexplicitly recommend its use.\n\nSigned-off-by: Patrick Steinhardt \n---\n Documentation/MyFirstContribution.adoc | 92 ++++++++++++++++++++++++++++++++--\n Documentation/SubmittingPatches | 6 ++-\n 2 files changed, 93 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc\nindex 984b7f5aa8..607876f3d8 100644\n--- a/Documentation/MyFirstContribution.adoc\n+++ b/Documentation/MyFirstContribution.adoc\n@@ -833,7 +833,7 @@ This patchset is part of the MyFirstContribution tutorial and should not\n be merged.\n ----\n \n-At this point the tutorial diverges, in order to demonstrate two\n+At this point the tutorial diverges, in order to demonstrate three\n different methods of formatting your patchset and getting it reviewed.\n \n The first method to be covered is GitGitGadget, which is useful for those\n@@ -845,9 +845,14 @@ more fine-grained control over the emails to be sent. This method requires some\n setup which can change depending on your system and will not be covered in this\n tutorial.\n \n+The third method to be covered is `b4`, which builds on top of `git\n+format-patch` and `git send-email`. This method is the recommended way to\n+submit patches via mail as it automates a lot of the bookkeeping required by\n+`git send-email`.\n+\n Regardless of which method you choose, your engagement with reviewers will be\n-the same; the review process will be covered after the sections on GitGitGadget\n-and `git send-email`.\n+the same; the review process will be covered after the sections on GitGitGadget,\n+`git send-email` and `b4`.\n \n [[howto-ggg]]\n == Sending Patches via GitGitGadget\n@@ -1296,6 +1301,87 @@ index 88f126184c..38da593a60 100644\n 2.21.0.392.gf8f6787159e-goog\n ----\n \n+[[howto-b4]]\n+== Sending Patches with `b4`\n+\n+`b4` is a tool that builds on top of `git format-patch` and `git send-email`.\n+It automates much of the bookkeeping involved in sending a patch series to a\n+mailing-list-based project.\n+\n+Refer to the https://b4.docs.kernel.org/[b4 documentation] for a full reference.\n+\n+[[prep-b4]]\n+=== Preparing a Patch Series\n+\n+`b4` tracks your patch series as a branch. To start tracking the `psuh` branch\n+you have been working on, run:\n+\n+----\n+$ b4 prep --enroll master\n+----\n+\n+This enrolls the current branch, using `master` as the base of the topic. `b4`\n+manages the cover letter as part of the branch, so you can edit it at any time\n+with:\n+\n+----\n+$ b4 prep --edit-cover\n+----\n+\n+The cover letter not only tracks the content of the top-level mail, but also\n+the set of recipients. You can add recipients by adding `To:` and `Cc:`\n+trailer lines.\n+\n+[[send-b4]]\n+=== Sending the Patches\n+\n+Before sending the series out for real, you can inspect what `b4` would send by\n+passing `--dry-run`:\n+\n+----\n+$ b4 send --dry-run\n+----\n+\n+Once you are happy with the result, send the series with:\n+\n+----\n+$ b4 send\n+----\n+\n+[[v2-b4]]\n+=== Sending v2\n+\n+When you are ready to send a new iteration of your series, refine your\n+patches as usual using linkgit:git-rebase[1]. Note that you typically want to\n+rebase on top of the cover letter. You can configure an alias to enable easy\n+rebases going forward:\n+\n+---\n+$ git config set alias.b4-rebase 'rebase \"HEAD^{/--- b4-submit-tracking ---}\"'\n+$ git b4-rebase -i\n+---\n+\n+Before sending out the new version you should also update the cover letter with\n+`b4 prep --edit-cover` to note the relevant changes compared to the previous\n+version. You can inspect the changes between the two versions with `b4 prep\n+--compare-to=v1`.\n+\n+Same as with the first version, you can use `b4 send` to send out the second\n+version. `b4` automatically bumps the version to `v2`, generates the range-diff\n+against the previous iteration, and threads the new series as a reply to the\n+cover letter of the first version.\n+\n+[[configure-b4]]\n+=== Configure b4\n+\n+`b4` can be configured via linkgit:git-config[1]. In addition to that, projects\n+can have their own set of defaults in `.b4-config` in the root tree, which also\n+uses Git's config format. The user's configuration always takes precedence over\n+the per-project defaults.\n+\n+Refer to the https://b4.docs.kernel.org/en/latest/config.html[b4 config documentation]\n+for more information on the available options.\n+\n [[now-what]]\n == My Patch Got Emailed - Now What?\n \ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex d570184ec8..99427e1ee1 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -573,8 +573,10 @@ your existing e-mail client (often optimized for \"multipart/*\" MIME\n type e-mails) might render your patches unusable.\n \n NOTE: Here we outline the procedure using `format-patch` and\n-`send-email`, but you can instead use GitGitGadget to send in your\n-patches (see link:MyFirstContribution.html[MyFirstContribution]).\n+`send-email`, but you can instead use GitGitGadget or `b4` to send in\n+your patches (see link:MyFirstContribution.html[MyFirstContribution]).\n+Contributors are encouraged to use `b4`, which automates much of the\n+bookkeeping that is otherwise done by hand.\n \n People on the Git mailing list need to be able to read and\n comment on the changes you are submitting. It is important for\n\n-- \n2.54.0.1136.gdb2ca164c4.dirty\n\n"},{"id":"544872","messageId":"20260608-pks-b4-v3-3-f5e497d10c56@pks.im","threadId":"65738","inReplyTo":"20260608-pks-b4-v3-0-f5e497d10c56@pks.im","subject":"[PATCH v3 3/3] b4: introduce configuration for the Git project","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-06-08T06:49:55Z","receivedAt":"2026-06-08T06:50:10Z","isPatch":true,"body":"We're about to extend our documentation to recommend b4 for sending\npatch series to the mailing list. Prepare for this by introducing a b4\nconfiguration so that the tool knows to honor our preferences. For now,\nthis configuration does two things:\n\n - It configures \"send-same-thread = shallow\", which tells b4 to always\n send subsequent versions of the same patch series as a reply to the\n cover letter of the first version.\n\n - It configures \"prep-cover-template\", which tells b4 to use a custom\n template for the cover letter. The most important change compared to\n the default template is that our custom template also includes a\n range-diff.\n\nThere's potentially more things that we may want to configure going\nforward, like for example auto-configuration of folks to Cc on certain\npatches. But these two tweaks feel like a good place to start.\n\nNote that these values only serve as defaults, and users may want to\ntweak those defaults based on their own preference. Luckily, users can\ndo that without having to touch `.b4-config` at all, as b4 allows them\nto override values via Git configuration:\n\n ```\n $ git config set b4.prep-cover-template /does/not/exist\n $ b4 send --dry-run\n ERROR: prep-cover-template says to use x, but it does not exist\n ```\n\nSo this gives users an easy way to override our defaults without having\nto touch \".b4-config\", which would dirty the tree.\n\nSigned-off-by: Patrick Steinhardt \n---\n .b4-config | 6 ++++++\n .b4-cover-template | 11 +++++++++++\n 2 files changed, 17 insertions(+)\n\ndiff --git a/.b4-config b/.b4-config\nnew file mode 100644\nindex 0000000000..fd4fb56b6d\n--- /dev/null\n+++ b/.b4-config\n@@ -0,0 +1,6 @@\n+# Note that these are default values that you can tweak via the typical\n+# git-config(1) machinery. You thus shouldn't ever have to change this file.\n+# See also https://b4.docs.kernel.org/en/latest/config.html.\n+[b4]\n+send-same-thread = shallow\n+prep-cover-template = ./.b4-cover-template\ndiff --git a/.b4-cover-template b/.b4-cover-template\nnew file mode 100644\nindex 0000000000..ab864933b5\n--- /dev/null\n+++ b/.b4-cover-template\n@@ -0,0 +1,11 @@\n+${cover}\n+\n+---\n+${shortlog}\n+\n+${diffstat}\n+\n+${range_diff}\n+---\n+base-commit: ${base_commit}\n+${prerequisites}\n\n-- \n2.54.0.1136.gdb2ca164c4.dirty\n\n"},{"id":"544875","messageId":"aiZ9hQ_SWTzxI3Ck@wyuan.org","threadId":"65738","inReplyTo":"aiZlu36Fh020L1Ip@pks.im","subject":"Re: [PATCH v2 1/3] Documentation/MyFirstContribution: recommend shallow threading","fromName":"Weijie Yuan","fromEmail":"wy@wyuan.org","sentAt":"2026-06-08T08:31:03Z","receivedAt":"2026-06-08T08:31:57Z","isPatch":true,"body":"On Mon, Jun 08, 2026 at 08:48:27AM +0200, Patrick Steinhardt wrote:\n> On Wed, Jun 03, 2026 at 06:29:32PM +0800, Weijie Yuan wrote:\n> > I'm afraid there will be some chaos.\n> \n> I think \"chaos\" is a bit exaggerated.\n\nOops, sorry for my poor English, I guess \"messy\" would be a more proper\nchoice here? ;-)\n\n> > As mentioned earlier, GitGitGadget now supports deep nesting of\n> > iterations, if b4 changes while GitGitGadget doesn't, it would be\n> > inconsistent in the archive. So, negotiation is necessary here.\n> \n> That's a good point though -- if we change the recommendation, we should\n> aim to change it consistently. I'll talk with Dscho (maintainer of GGG)\n> today.\n\nThanks for your effort on this! Let´s see if the community can get on\nthe same page about this.\n\nThanks!\n"},{"id":"545063","messageId":"87a4t32a4g.fsf@emacs.iotcl.com","threadId":"65738","inReplyTo":"20260608-pks-b4-v3-0-f5e497d10c56@pks.im","subject":"Re: [PATCH v3 0/3] Documentation: recommend the use of b4","fromName":"Toon Claes","fromEmail":"toon@iotcl.com","sentAt":"2026-06-09T12:04:15Z","receivedAt":"2026-06-09T12:04:23Z","isPatch":true,"body":"Patrick Steinhardt writes:\n\n> Hi,\n>\n> this small patch series wires up b4 in Git and recommends the use\n> thereof via \"MyFirstContribution\", as discussed in [1].\n>\n> Changes in v3:\n> - I wasn't really able to judge consensus one way or the other\n> regarding the deep vs shallow nesting of cover letters, so I still\n> have the change to shallow nesting of cover letters part of this\n> series. If we continue to be split on this one (or if we favor the\n> current status quo) I'm happy to drop the first patch and adapt the\n> last patch to use deep nesting of cover letters instead.\n\nPersonally I don't care too much. I'm used to the shallow threading, so\nI'm fine with that.\n\nNow on the other hand, looking at a few examples I see GitGitGadget does\ndeep nesting. Wouldn't it make sense to be consistent?\n\nAnyhow, I don't think it's worth it to keep bike shedding about this. In\nall methods we recommend to Cc people, I think that's more important\nthen caring about how messages are threaded (for example, I've noticed\nLKML doesn't thread at all, i.e. `b4.send-same-thread=no` which is the\ndefault).\n\nBottom line, for me this series is good to go in.\n\n-- \nCheers,\nToon\n"},{"id":"545073","messageId":"xmqqh5nbsuxu.fsf@gitster.g","threadId":"65738","inReplyTo":"87a4t32a4g.fsf@emacs.iotcl.com","subject":"Re: [PATCH v3 0/3] Documentation: recommend the use of b4","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-06-09T13:30:05Z","receivedAt":"2026-06-09T13:30:10Z","isPatch":true,"body":"Toon Claes writes:\n\n> Anyhow, I don't think it's worth it to keep bike shedding about this. In\n> all methods we recommend to Cc people, I think that's more important\n> then\n\nGood point to stress about whom to involve.\n\n> caring about how messages are threaded (for example, I've noticed\n> LKML doesn't thread at all, i.e. `b4.send-same-thread=no` which is the\n> default).\n\nAs long as it does not hurt automation, I do not care too much, but\nthat default is somewhat surprising to me. The setting actively\ndiscourages tools from finding previous iterations.\n\n> Bottom line, for me this series is good to go in.\n\nYeah, sounds good to me.\n"},{"id":"545097","messageId":"aikHVTYVGw23E_Se@pks.im","threadId":"65738","inReplyTo":"87a4t32a4g.fsf@emacs.iotcl.com","subject":"Re: [PATCH v3 0/3] Documentation: recommend the use of b4","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-06-10T06:42:29Z","receivedAt":"2026-06-10T06:42:36Z","isPatch":true,"body":"On Tue, Jun 09, 2026 at 02:04:15PM +0200, Toon Claes wrote:\n> Patrick Steinhardt writes:\n> Now on the other hand, looking at a few examples I see GitGitGadget does\n> deep nesting. Wouldn't it make sense to be consistent?\n\nI've chatted with Dscho about this, and he mentioned that Stolee has\nalready opened [1]. So yes, if we agree to change the recommendation we\nshould also adapt GGG.\n\nPatrick\n\n[1]: https://github.com/gitgitgadget/gitgitgadget/issues/2254\n"},{"id":"545129","messageId":"CAOLa=ZQE-kkpSX=pP2A6SXdbp_O6AHzRmbUDOtKCsvz2Yz66Ng@mail.gmail.com","threadId":"65738","inReplyTo":"20260608-pks-b4-v3-1-f5e497d10c56@pks.im","subject":"Re: [PATCH v3 1/3] MyFirstContribution: recommend shallow threading of cover letters","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-06-10T11:08:33Z","receivedAt":"2026-06-10T11:08:35Z","isPatch":true,"body":"Patrick Steinhardt writes:\n\n> The \"MyFirstContribution\" document recommends the use of deep threading\n> of cover letters: every cover letter of subsequent iterations shall be\n> linked to the cover letter of the preceding version. The result of this\n> is that eventually, threads with many versions are getting nested so\n> deep that it becomes hard to follow.\n>\n> Adapt the recommendation to instead propose shallow threading of cover\n> letters: instead of linking the cover letter to the previous cover\n> letter, the user is supposed to always link it to the first cover\n> letter. This still makes it easy to follow the iterations, but has the\n> benefit of nesting to a much shallower level.\n\nShould we also modify 'Documentation/SubmittingPatches'? Which states:\n\n All subsequent versions of a patch series and other related patches\n should be grouped into their own e-mail thread to help readers find\n all parts of the series. To that end, send them as replies to either\n an additional \"cover letter\" message (see below), the first patch, or\n the respective preceding patch. Here is a\n link:MyFirstContribution.html#v2-git-send-email[step-by-step guide] on\n how to submit updated versions of a patch series.\n\nPersonally, I find it a bit awkward when new versions are sent as a new\nseparate thread, especially when the subject is changed over versions.\n\n>\n> Signed-off-by: Patrick Steinhardt \n> ---\n> Documentation/MyFirstContribution.adoc | 8 ++++----\n> 1 file changed, 4 insertions(+), 4 deletions(-)\n>\n> diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc\n> index b9fdefce02..984b7f5aa8 100644\n> --- a/Documentation/MyFirstContribution.adoc\n> +++ b/Documentation/MyFirstContribution.adoc\n> @@ -790,7 +790,7 @@ We can note a few things:\n> v3\", etc. in place of \"PATCH\". For example, \"[PATCH v2 1/3]\" would be the first of\n> three patches in the second iteration. Each iteration is sent with a new cover\n> letter (like \"[PATCH v2 0/3]\" above), itself a reply to the cover letter of the\n> - previous iteration (more on that below).\n> + first iteration (more on that below).\n>\n> NOTE: A single-patch topic is sent with \"[PATCH]\", \"[PATCH v2]\", etc. without\n> _i_/_n_ numbering (in the above thread overview, no single-patch topic appears,\n> @@ -1214,7 +1214,7 @@ between your last version and now, if it's something significant. You do not\n> need the exact same body in your second cover letter; focus on explaining to\n> reviewers the changes you've made that may not be as visible.\n>\n> -You will also need to go and find the Message-ID of your previous cover letter.\n> +You will also need to go and find the Message-ID of your first cover letter.\n> You can either note it when you send the first series, from the output of `git\n> send-email`, or you can look it up on the\n> https://lore.kernel.org/git[mailing list]. Find your cover letter in the\n> @@ -1227,8 +1227,8 @@ Message-ID: \n>\n> Your Message-ID is ``. This example will be used\n> below as well; make sure to replace it with the correct Message-ID for your\n> -**previous cover letter** - that is, if you're sending v2, use the Message-ID\n> -from v1; if you're sending v3, use the Message-ID from v2.\n> +**first cover letter** - that is, for any subsequent version that you send,\n> +always use the Message-ID from v1.\n>\n> While you're looking at the email, you should also note who is CC'd, as it's\n> common practice in the mailing list to keep all CCs on a thread. You can add\n>\n> --\n> 2.54.0.1136.gdb2ca164c4.dirty\n\nThe patch looks good.\n"},{"id":"545130","messageId":"CAOLa=ZQxA52p+9DcZZ=gVTqZ66ETQvZRQYjZNFjzdbsPwTW2iQ@mail.gmail.com","threadId":"65738","inReplyTo":"20260608-pks-b4-v3-3-f5e497d10c56@pks.im","subject":"Re: [PATCH v3 3/3] b4: introduce configuration for the Git project","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-06-10T11:13:33Z","receivedAt":"2026-06-10T11:13:35Z","isPatch":true,"body":"Patrick Steinhardt writes:\n\n> We're about to extend our documentation to recommend b4 for sending\n\nNit: This is in the past now\n\n> patch series to the mailing list. Prepare for this by introducing a b4\n> configuration so that the tool knows to honor our preferences. For now,\n> this configuration does two things:\n>\n> - It configures \"send-same-thread = shallow\", which tells b4 to always\n> send subsequent versions of the same patch series as a reply to the\n> cover letter of the first version.\n>\n> - It configures \"prep-cover-template\", which tells b4 to use a custom\n> template for the cover letter. The most important change compared to\n> the default template is that our custom template also includes a\n> range-diff.\n>\n> There's potentially more things that we may want to configure going\n> forward, like for example auto-configuration of folks to Cc on certain\n> patches. But these two tweaks feel like a good place to start.\n>\n> Note that these values only serve as defaults, and users may want to\n> tweak those defaults based on their own preference. Luckily, users can\n> do that without having to touch `.b4-config` at all, as b4 allows them\n> to override values via Git configuration:\n>\n> ```\n> $ git config set b4.prep-cover-template /does/not/exist\n> $ b4 send --dry-run\n> ERROR: prep-cover-template says to use x, but it does not exist\n> ```\n>\n> So this gives users an easy way to override our defaults without having\n> to touch \".b4-config\", which would dirty the tree.\n>\n> Signed-off-by: Patrick Steinhardt \n> ---\n> .b4-config | 6 ++++++\n> .b4-cover-template | 11 +++++++++++\n> 2 files changed, 17 insertions(+)\n>\n> diff --git a/.b4-config b/.b4-config\n> new file mode 100644\n> index 0000000000..fd4fb56b6d\n> --- /dev/null\n> +++ b/.b4-config\n> @@ -0,0 +1,6 @@\n> +# Note that these are default values that you can tweak via the typical\n> +# git-config(1) machinery. You thus shouldn't ever have to change this file.\n> +# See also https://b4.docs.kernel.org/en/latest/config.html.\n> +[b4]\n> +send-same-thread = shallow\n> +prep-cover-template = ./.b4-cover-template\n> diff --git a/.b4-cover-template b/.b4-cover-template\n> new file mode 100644\n> index 0000000000..ab864933b5\n> --- /dev/null\n> +++ b/.b4-cover-template\n> @@ -0,0 +1,11 @@\n> +${cover}\n> +\n> +---\n> +${shortlog}\n> +\n> +${diffstat}\n> +\n> +${range_diff}\n> +---\n> +base-commit: ${base_commit}\n> +${prerequisites}\n>\n\nThis looks similar to what I have locally too, happy to see this land.\n\n> --\n> 2.54.0.1136.gdb2ca164c4.dirty\n"},{"id":"545555","messageId":"ai_26l4sYwK09kdY@pks.im","threadId":"65738","inReplyTo":"CAOLa=ZQE-kkpSX=pP2A6SXdbp_O6AHzRmbUDOtKCsvz2Yz66Ng@mail.gmail.com","subject":"Re: [PATCH v3 1/3] MyFirstContribution: recommend shallow threading of cover letters","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-06-15T12:58:18Z","receivedAt":"2026-06-15T12:58:26Z","isPatch":true,"body":"On Wed, Jun 10, 2026 at 07:08:33AM -0400, Karthik Nayak wrote:\n> Patrick Steinhardt writes:\n> \n> > The \"MyFirstContribution\" document recommends the use of deep threading\n> > of cover letters: every cover letter of subsequent iterations shall be\n> > linked to the cover letter of the preceding version. The result of this\n> > is that eventually, threads with many versions are getting nested so\n> > deep that it becomes hard to follow.\n> >\n> > Adapt the recommendation to instead propose shallow threading of cover\n> > letters: instead of linking the cover letter to the previous cover\n> > letter, the user is supposed to always link it to the first cover\n> > letter. This still makes it easy to follow the iterations, but has the\n> > benefit of nesting to a much shallower level.\n> \n> Should we also modify 'Documentation/SubmittingPatches'? Which states:\n> \n> All subsequent versions of a patch series and other related patches\n> should be grouped into their own e-mail thread to help readers find\n> all parts of the series. To that end, send them as replies to either\n> an additional \"cover letter\" message (see below), the first patch, or\n> the respective preceding patch. Here is a\n> link:MyFirstContribution.html#v2-git-send-email[step-by-step guide] on\n> how to submit updated versions of a patch series.\n> \n> Personally, I find it a bit awkward when new versions are sent as a new\n> separate thread, especially when the subject is changed over versions.\n\nI don't necessarily see this as contradicting advice, I rather read it\nas \"patches of vN+1 should have their own subthread\". But it certainly\nis confusingly written, and I'm not even sure myself whether I'm reading\nit correctly or not.\n\nI kind of feel like this is a bit outside the scope of this series. Also\nbecause I'm not a 100% sure how to reword this to make it read nicer :)\nBut I'm very happy to accept suggestions here.\n\nPatrick\n"},{"id":"545556","messageId":"ai_273yFlPQXuMDp@pks.im","threadId":"65738","inReplyTo":"CAOLa=ZQxA52p+9DcZZ=gVTqZ66ETQvZRQYjZNFjzdbsPwTW2iQ@mail.gmail.com","subject":"Re: [PATCH v3 3/3] b4: introduce configuration for the Git project","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-06-15T12:58:23Z","receivedAt":"2026-06-15T12:58:28Z","isPatch":true,"body":"On Wed, Jun 10, 2026 at 07:13:33AM -0400, Karthik Nayak wrote:\n> Patrick Steinhardt writes:\n> \n> > We're about to extend our documentation to recommend b4 for sending\n> \n> Nit: This is in the past now\n\nTrue, will fix.\n\nPatrick\n"},{"id":"545557","messageId":"20260615-pks-b4-v4-0-22cfca8f19c5@pks.im","threadId":"65738","inReplyTo":"20260602-pks-b4-v1-0-a7ae5a49e9cf@pks.im","subject":"[PATCH v4 0/3] Documentation: recommend the use of b4","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-06-15T12:59:40Z","receivedAt":"2026-06-15T12:59:52Z","isPatch":true,"body":"Hi,\n\nthis small patch series wires up b4 in Git and recommends the use\nthereof via \"MyFirstContribution\", as discussed in [1].\n\nChanges in v4:\n - Improve a commit message.\n - Link to v3: https://patch.msgid.link/20260608-pks-b4-v3-0-f5e497d10c56@pks.im\n\nChanges in v3:\n - I wasn't really able to judge consensus one way or the other\n regarding the deep vs shallow nesting of cover letters, so I still\n have the change to shallow nesting of cover letters part of this\n series. If we continue to be split on this one (or if we favor the\n current status quo) I'm happy to drop the first patch and adapt the\n last patch to use deep nesting of cover letters instead.\n - Hopefully fix some confusion by saying \"shallow/deep threading of\n cover letters\".\n - Fix some more instances where we recommend deep threading of cover\n letters.\n - Link to v2: https://patch.msgid.link/20260603-pks-b4-v2-0-a8aea0aa2c23@pks.im\n\nChanges in v2:\n - Reorder commits so that the b4 docs are added first.\n - Add a section that highlights how to configure b4, and that points\n out that the per-project defaults can be overridden via Git\n configuration.\n - Add a patch to MyFirstContribution that recommends shallow\n threading. I mostly intend this to be a discussion starter so that\n the `.b4-config` file matches our preferred threading style.\n - Fix a typo.\n - Link to v1: https://patch.msgid.link/20260602-pks-b4-v1-0-a7ae5a49e9cf@pks.im\n\nThanks!\n\nPatrick\n\n[1]: \n\n---\nPatrick Steinhardt (3):\n MyFirstContribution: recommend shallow threading of cover letters\n MyFirstContribution: recommend the use of b4\n b4: introduce configuration for the Git project\n\n .b4-config | 6 ++\n .b4-cover-template | 11 ++++\n Documentation/MyFirstContribution.adoc | 100 ++++++++++++++++++++++++++++++---\n Documentation/SubmittingPatches | 6 +-\n 4 files changed, 114 insertions(+), 9 deletions(-)\n\nRange-diff versus v3:\n\n1: 1aec56f76c = 1: b6b488e6a8 MyFirstContribution: recommend shallow threading of cover letters\n2: f2036769bd = 2: 1a68b993d2 MyFirstContribution: recommend the use of b4\n3: fb522c7d90 ! 3: 5bc8fba96a b4: introduce configuration for the Git project\n @@ Metadata\n ## Commit message ##\n b4: introduce configuration for the Git project\n \n - We're about to extend our documentation to recommend b4 for sending\n - patch series to the mailing list. Prepare for this by introducing a b4\n - configuration so that the tool knows to honor our preferences. For now,\n - this configuration does two things:\n + In the preceding commit we have extended our documentation to recommend\n + b4 for sending patch series to the mailing list. Introduce configuration\n + so that it knows to honor preferences of the Git project by default. For\n + now, this configuration does two things:\n \n - It configures \"send-same-thread = shallow\", which tells b4 to always\n send subsequent versions of the same patch series as a reply to the\n\n---\nbase-commit: 9ac3f193c05c2237e2b14ebaa1149e9fc8a1abe0\nchange-id: 20260602-pks-b4-31cc20d7f84b\n\n"},{"id":"545558","messageId":"20260615-pks-b4-v4-1-22cfca8f19c5@pks.im","threadId":"65738","inReplyTo":"20260615-pks-b4-v4-0-22cfca8f19c5@pks.im","subject":"[PATCH v4 1/3] MyFirstContribution: recommend shallow threading of cover letters","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-06-15T12:59:41Z","receivedAt":"2026-06-15T12:59:54Z","isPatch":true,"body":"The \"MyFirstContribution\" document recommends the use of deep threading\nof cover letters: every cover letter of subsequent iterations shall be\nlinked to the cover letter of the preceding version. The result of this\nis that eventually, threads with many versions are getting nested so\ndeep that it becomes hard to follow.\n\nAdapt the recommendation to instead propose shallow threading of cover\nletters: instead of linking the cover letter to the previous cover\nletter, the user is supposed to always link it to the first cover\nletter. This still makes it easy to follow the iterations, but has the\nbenefit of nesting to a much shallower level.\n\nSigned-off-by: Patrick Steinhardt \n---\n Documentation/MyFirstContribution.adoc | 8 ++++----\n 1 file changed, 4 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc\nindex b9fdefce02..984b7f5aa8 100644\n--- a/Documentation/MyFirstContribution.adoc\n+++ b/Documentation/MyFirstContribution.adoc\n@@ -790,7 +790,7 @@ We can note a few things:\n v3\", etc. in place of \"PATCH\". For example, \"[PATCH v2 1/3]\" would be the first of\n three patches in the second iteration. Each iteration is sent with a new cover\n letter (like \"[PATCH v2 0/3]\" above), itself a reply to the cover letter of the\n- previous iteration (more on that below).\n+ first iteration (more on that below).\n \n NOTE: A single-patch topic is sent with \"[PATCH]\", \"[PATCH v2]\", etc. without\n _i_/_n_ numbering (in the above thread overview, no single-patch topic appears,\n@@ -1214,7 +1214,7 @@ between your last version and now, if it's something significant. You do not\n need the exact same body in your second cover letter; focus on explaining to\n reviewers the changes you've made that may not be as visible.\n \n-You will also need to go and find the Message-ID of your previous cover letter.\n+You will also need to go and find the Message-ID of your first cover letter.\n You can either note it when you send the first series, from the output of `git\n send-email`, or you can look it up on the\n https://lore.kernel.org/git[mailing list]. Find your cover letter in the\n@@ -1227,8 +1227,8 @@ Message-ID: \n \n Your Message-ID is ``. This example will be used\n below as well; make sure to replace it with the correct Message-ID for your\n-**previous cover letter** - that is, if you're sending v2, use the Message-ID\n-from v1; if you're sending v3, use the Message-ID from v2.\n+**first cover letter** - that is, for any subsequent version that you send,\n+always use the Message-ID from v1.\n \n While you're looking at the email, you should also note who is CC'd, as it's\n common practice in the mailing list to keep all CCs on a thread. You can add\n\n-- \n2.55.0.rc0.738.g0c8ab3ebcc.dirty\n\n"},{"id":"545559","messageId":"20260615-pks-b4-v4-2-22cfca8f19c5@pks.im","threadId":"65738","inReplyTo":"20260615-pks-b4-v4-0-22cfca8f19c5@pks.im","subject":"[PATCH v4 2/3] MyFirstContribution: recommend the use of b4","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-06-15T12:59:42Z","receivedAt":"2026-06-15T12:59:57Z","isPatch":true,"body":"The b4 tool originates from the Linux kernel community and is intended\nto help mailing-list based workflows. It automates a lot of the annoying\nbookkeeping tasks that contributors typically need to do: tracking the\nlist of recipients, Message-IDs, range-diffs and the like. In addition\nto that, b4 also has many other subcommands that help the maintainer and\nreviewers.\n\nThe Git project uses the same infrastructure as the kernel, so this tool\nis also a very good fit for us. Adapt \"MyFirstContribution\" to\nexplicitly recommend its use.\n\nSigned-off-by: Patrick Steinhardt \n---\n Documentation/MyFirstContribution.adoc | 92 ++++++++++++++++++++++++++++++++--\n Documentation/SubmittingPatches | 6 ++-\n 2 files changed, 93 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc\nindex 984b7f5aa8..607876f3d8 100644\n--- a/Documentation/MyFirstContribution.adoc\n+++ b/Documentation/MyFirstContribution.adoc\n@@ -833,7 +833,7 @@ This patchset is part of the MyFirstContribution tutorial and should not\n be merged.\n ----\n \n-At this point the tutorial diverges, in order to demonstrate two\n+At this point the tutorial diverges, in order to demonstrate three\n different methods of formatting your patchset and getting it reviewed.\n \n The first method to be covered is GitGitGadget, which is useful for those\n@@ -845,9 +845,14 @@ more fine-grained control over the emails to be sent. This method requires some\n setup which can change depending on your system and will not be covered in this\n tutorial.\n \n+The third method to be covered is `b4`, which builds on top of `git\n+format-patch` and `git send-email`. This method is the recommended way to\n+submit patches via mail as it automates a lot of the bookkeeping required by\n+`git send-email`.\n+\n Regardless of which method you choose, your engagement with reviewers will be\n-the same; the review process will be covered after the sections on GitGitGadget\n-and `git send-email`.\n+the same; the review process will be covered after the sections on GitGitGadget,\n+`git send-email` and `b4`.\n \n [[howto-ggg]]\n == Sending Patches via GitGitGadget\n@@ -1296,6 +1301,87 @@ index 88f126184c..38da593a60 100644\n 2.21.0.392.gf8f6787159e-goog\n ----\n \n+[[howto-b4]]\n+== Sending Patches with `b4`\n+\n+`b4` is a tool that builds on top of `git format-patch` and `git send-email`.\n+It automates much of the bookkeeping involved in sending a patch series to a\n+mailing-list-based project.\n+\n+Refer to the https://b4.docs.kernel.org/[b4 documentation] for a full reference.\n+\n+[[prep-b4]]\n+=== Preparing a Patch Series\n+\n+`b4` tracks your patch series as a branch. To start tracking the `psuh` branch\n+you have been working on, run:\n+\n+----\n+$ b4 prep --enroll master\n+----\n+\n+This enrolls the current branch, using `master` as the base of the topic. `b4`\n+manages the cover letter as part of the branch, so you can edit it at any time\n+with:\n+\n+----\n+$ b4 prep --edit-cover\n+----\n+\n+The cover letter not only tracks the content of the top-level mail, but also\n+the set of recipients. You can add recipients by adding `To:` and `Cc:`\n+trailer lines.\n+\n+[[send-b4]]\n+=== Sending the Patches\n+\n+Before sending the series out for real, you can inspect what `b4` would send by\n+passing `--dry-run`:\n+\n+----\n+$ b4 send --dry-run\n+----\n+\n+Once you are happy with the result, send the series with:\n+\n+----\n+$ b4 send\n+----\n+\n+[[v2-b4]]\n+=== Sending v2\n+\n+When you are ready to send a new iteration of your series, refine your\n+patches as usual using linkgit:git-rebase[1]. Note that you typically want to\n+rebase on top of the cover letter. You can configure an alias to enable easy\n+rebases going forward:\n+\n+---\n+$ git config set alias.b4-rebase 'rebase \"HEAD^{/--- b4-submit-tracking ---}\"'\n+$ git b4-rebase -i\n+---\n+\n+Before sending out the new version you should also update the cover letter with\n+`b4 prep --edit-cover` to note the relevant changes compared to the previous\n+version. You can inspect the changes between the two versions with `b4 prep\n+--compare-to=v1`.\n+\n+Same as with the first version, you can use `b4 send` to send out the second\n+version. `b4` automatically bumps the version to `v2`, generates the range-diff\n+against the previous iteration, and threads the new series as a reply to the\n+cover letter of the first version.\n+\n+[[configure-b4]]\n+=== Configure b4\n+\n+`b4` can be configured via linkgit:git-config[1]. In addition to that, projects\n+can have their own set of defaults in `.b4-config` in the root tree, which also\n+uses Git's config format. The user's configuration always takes precedence over\n+the per-project defaults.\n+\n+Refer to the https://b4.docs.kernel.org/en/latest/config.html[b4 config documentation]\n+for more information on the available options.\n+\n [[now-what]]\n == My Patch Got Emailed - Now What?\n \ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nindex d570184ec8..99427e1ee1 100644\n--- a/Documentation/SubmittingPatches\n+++ b/Documentation/SubmittingPatches\n@@ -573,8 +573,10 @@ your existing e-mail client (often optimized for \"multipart/*\" MIME\n type e-mails) might render your patches unusable.\n \n NOTE: Here we outline the procedure using `format-patch` and\n-`send-email`, but you can instead use GitGitGadget to send in your\n-patches (see link:MyFirstContribution.html[MyFirstContribution]).\n+`send-email`, but you can instead use GitGitGadget or `b4` to send in\n+your patches (see link:MyFirstContribution.html[MyFirstContribution]).\n+Contributors are encouraged to use `b4`, which automates much of the\n+bookkeeping that is otherwise done by hand.\n \n People on the Git mailing list need to be able to read and\n comment on the changes you are submitting. It is important for\n\n-- \n2.55.0.rc0.738.g0c8ab3ebcc.dirty\n\n"},{"id":"545560","messageId":"20260615-pks-b4-v4-3-22cfca8f19c5@pks.im","threadId":"65738","inReplyTo":"20260615-pks-b4-v4-0-22cfca8f19c5@pks.im","subject":"[PATCH v4 3/3] b4: introduce configuration for the Git project","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-06-15T12:59:43Z","receivedAt":"2026-06-15T12:59:59Z","isPatch":true,"body":"In the preceding commit we have extended our documentation to recommend\nb4 for sending patch series to the mailing list. Introduce configuration\nso that it knows to honor preferences of the Git project by default. For\nnow, this configuration does two things:\n\n - It configures \"send-same-thread = shallow\", which tells b4 to always\n send subsequent versions of the same patch series as a reply to the\n cover letter of the first version.\n\n - It configures \"prep-cover-template\", which tells b4 to use a custom\n template for the cover letter. The most important change compared to\n the default template is that our custom template also includes a\n range-diff.\n\nThere's potentially more things that we may want to configure going\nforward, like for example auto-configuration of folks to Cc on certain\npatches. But these two tweaks feel like a good place to start.\n\nNote that these values only serve as defaults, and users may want to\ntweak those defaults based on their own preference. Luckily, users can\ndo that without having to touch `.b4-config` at all, as b4 allows them\nto override values via Git configuration:\n\n ```\n $ git config set b4.prep-cover-template /does/not/exist\n $ b4 send --dry-run\n ERROR: prep-cover-template says to use x, but it does not exist\n ```\n\nSo this gives users an easy way to override our defaults without having\nto touch \".b4-config\", which would dirty the tree.\n\nSigned-off-by: Patrick Steinhardt \n---\n .b4-config | 6 ++++++\n .b4-cover-template | 11 +++++++++++\n 2 files changed, 17 insertions(+)\n\ndiff --git a/.b4-config b/.b4-config\nnew file mode 100644\nindex 0000000000..fd4fb56b6d\n--- /dev/null\n+++ b/.b4-config\n@@ -0,0 +1,6 @@\n+# Note that these are default values that you can tweak via the typical\n+# git-config(1) machinery. You thus shouldn't ever have to change this file.\n+# See also https://b4.docs.kernel.org/en/latest/config.html.\n+[b4]\n+send-same-thread = shallow\n+prep-cover-template = ./.b4-cover-template\ndiff --git a/.b4-cover-template b/.b4-cover-template\nnew file mode 100644\nindex 0000000000..ab864933b5\n--- /dev/null\n+++ b/.b4-cover-template\n@@ -0,0 +1,11 @@\n+${cover}\n+\n+---\n+${shortlog}\n+\n+${diffstat}\n+\n+${range_diff}\n+---\n+base-commit: ${base_commit}\n+${prerequisites}\n\n-- \n2.55.0.rc0.738.g0c8ab3ebcc.dirty\n\n"},{"id":"545626","messageId":"87eci7yomp.fsf@emacs.iotcl.com","threadId":"65738","inReplyTo":"20260615-pks-b4-v4-0-22cfca8f19c5@pks.im","subject":"Re: [PATCH v4 0/3] Documentation: recommend the use of b4","fromName":"Toon Claes","fromEmail":"toon@iotcl.com","sentAt":"2026-06-16T06:40:14Z","receivedAt":"2026-06-16T06:40:26Z","isPatch":true,"body":"Patrick Steinhardt writes:\n\n> Hi,\n>\n> this small patch series wires up b4 in Git and recommends the use\n> thereof via \"MyFirstContribution\", as discussed in [1].\n>\n> Changes in v4:\n> - Improve a commit message.\n> - Link to v3: https://patch.msgid.link/20260608-pks-b4-v3-0-f5e497d10c56@pks.im\n>\n> Changes in v3:\n> - I wasn't really able to judge consensus one way or the other\n> regarding the deep vs shallow nesting of cover letters, so I still\n> have the change to shallow nesting of cover letters part of this\n> series. If we continue to be split on this one (or if we favor the\n> current status quo) I'm happy to drop the first patch and adapt the\n> last patch to use deep nesting of cover letters instead.\n> - Hopefully fix some confusion by saying \"shallow/deep threading of\n> cover letters\".\n> - Fix some more instances where we recommend deep threading of cover\n> letters.\n> - Link to v2: https://patch.msgid.link/20260603-pks-b4-v2-0-a8aea0aa2c23@pks.im\n>\n> Changes in v2:\n> - Reorder commits so that the b4 docs are added first.\n> - Add a section that highlights how to configure b4, and that points\n> out that the per-project defaults can be overridden via Git\n> configuration.\n> - Add a patch to MyFirstContribution that recommends shallow\n> threading. I mostly intend this to be a discussion starter so that\n> the `.b4-config` file matches our preferred threading style.\n> - Fix a typo.\n> - Link to v1: https://patch.msgid.link/20260602-pks-b4-v1-0-a7ae5a49e9cf@pks.im\n>\n> Thanks!\n>\n> Patrick\n>\n> [1]: \n>\n> ---\n> Patrick Steinhardt (3):\n> MyFirstContribution: recommend shallow threading of cover letters\n> MyFirstContribution: recommend the use of b4\n> b4: introduce configuration for the Git project\n>\n> .b4-config | 6 ++\n> .b4-cover-template | 11 ++++\n> Documentation/MyFirstContribution.adoc | 100 ++++++++++++++++++++++++++++++---\n> Documentation/SubmittingPatches | 6 +-\n> 4 files changed, 114 insertions(+), 9 deletions(-)\n>\n> Range-diff versus v3:\n>\n> 1: 1aec56f76c = 1: b6b488e6a8 MyFirstContribution: recommend shallow threading of cover letters\n> 2: f2036769bd = 2: 1a68b993d2 MyFirstContribution: recommend the use of b4\n> 3: fb522c7d90 ! 3: 5bc8fba96a b4: introduce configuration for the Git project\n> @@ Metadata\n> ## Commit message ##\n> b4: introduce configuration for the Git project\n> \n> - We're about to extend our documentation to recommend b4 for sending\n> - patch series to the mailing list. Prepare for this by introducing a b4\n> - configuration so that the tool knows to honor our preferences. For now,\n> - this configuration does two things:\n> + In the preceding commit we have extended our documentation to recommend\n> + b4 for sending patch series to the mailing list. Introduce configuration\n> + so that it knows to honor preferences of the Git project by default. For\n> + now, this configuration does two things:\n> \n> - It configures \"send-same-thread = shallow\", which tells b4 to always\n> send subsequent versions of the same patch series as a reply to the\n\nNo further comments based on the range-diff.\n\n-- \nCheers,\nToon\n"}]}