From 16b2924aab52141bedd6612dfad16280181321c7 Mon Sep 17 00:00:00 2001 From: Patrick Steinhardt Date: Mon, 15 Jun 2026 14:59:41 +0200 Subject: [PATCH 1/3] MyFirstContribution: recommend shallow threading of cover letters The "MyFirstContribution" document recommends the use of deep threading of cover letters: every cover letter of subsequent iterations shall be linked to the cover letter of the preceding version. The result of this is that eventually, threads with many versions are getting nested so deep that it becomes hard to follow. Adapt the recommendation to instead propose shallow threading of cover letters: instead of linking the cover letter to the previous cover letter, the user is supposed to always link it to the first cover letter. This still makes it easy to follow the iterations, but has the benefit of nesting to a much shallower level. Signed-off-by: Patrick Steinhardt Signed-off-by: Junio C Hamano --- Documentation/MyFirstContribution.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc index b9fdefce02..984b7f5aa8 100644 --- a/Documentation/MyFirstContribution.adoc +++ b/Documentation/MyFirstContribution.adoc @@ -790,7 +790,7 @@ We can note a few things: v3", etc. in place of "PATCH". For example, "[PATCH v2 1/3]" would be the first of three patches in the second iteration. Each iteration is sent with a new cover letter (like "[PATCH v2 0/3]" above), itself a reply to the cover letter of the - previous iteration (more on that below). + first iteration (more on that below). NOTE: A single-patch topic is sent with "[PATCH]", "[PATCH v2]", etc. without _i_/_n_ numbering (in the above thread overview, no single-patch topic appears, @@ -1214,7 +1214,7 @@ between your last version and now, if it's something significant. You do not need the exact same body in your second cover letter; focus on explaining to reviewers the changes you've made that may not be as visible. -You will also need to go and find the Message-ID of your previous cover letter. +You will also need to go and find the Message-ID of your first cover letter. You can either note it when you send the first series, from the output of `git send-email`, or you can look it up on the https://lore.kernel.org/git[mailing list]. Find your cover letter in the @@ -1227,8 +1227,8 @@ Message-ID: Your Message-ID is ``. This example will be used below as well; make sure to replace it with the correct Message-ID for your -**previous cover letter** - that is, if you're sending v2, use the Message-ID -from v1; if you're sending v3, use the Message-ID from v2. +**first cover letter** - that is, for any subsequent version that you send, +always use the Message-ID from v1. While you're looking at the email, you should also note who is CC'd, as it's common practice in the mailing list to keep all CCs on a thread. You can add From efe4ac70647c62152c37f2f247404c9dfd494ed5 Mon Sep 17 00:00:00 2001 From: Patrick Steinhardt Date: Mon, 15 Jun 2026 14:59:42 +0200 Subject: [PATCH 2/3] MyFirstContribution: recommend the use of b4 The b4 tool originates from the Linux kernel community and is intended to help mailing-list based workflows. It automates a lot of the annoying bookkeeping tasks that contributors typically need to do: tracking the list of recipients, Message-IDs, range-diffs and the like. In addition to that, b4 also has many other subcommands that help the maintainer and reviewers. The Git project uses the same infrastructure as the kernel, so this tool is also a very good fit for us. Adapt "MyFirstContribution" to explicitly recommend its use. Signed-off-by: Patrick Steinhardt Signed-off-by: Junio C Hamano --- Documentation/MyFirstContribution.adoc | 92 +++++++++++++++++++++++++- Documentation/SubmittingPatches | 6 +- 2 files changed, 93 insertions(+), 5 deletions(-) diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc index 984b7f5aa8..607876f3d8 100644 --- a/Documentation/MyFirstContribution.adoc +++ b/Documentation/MyFirstContribution.adoc @@ -833,7 +833,7 @@ This patchset is part of the MyFirstContribution tutorial and should not be merged. ---- -At this point the tutorial diverges, in order to demonstrate two +At this point the tutorial diverges, in order to demonstrate three different methods of formatting your patchset and getting it reviewed. The first method to be covered is GitGitGadget, which is useful for those @@ -845,9 +845,14 @@ more fine-grained control over the emails to be sent. This method requires some setup which can change depending on your system and will not be covered in this tutorial. +The third method to be covered is `b4`, which builds on top of `git +format-patch` and `git send-email`. This method is the recommended way to +submit patches via mail as it automates a lot of the bookkeeping required by +`git send-email`. + Regardless of which method you choose, your engagement with reviewers will be -the same; the review process will be covered after the sections on GitGitGadget -and `git send-email`. +the same; the review process will be covered after the sections on GitGitGadget, +`git send-email` and `b4`. [[howto-ggg]] == Sending Patches via GitGitGadget @@ -1296,6 +1301,87 @@ index 88f126184c..38da593a60 100644 2.21.0.392.gf8f6787159e-goog ---- +[[howto-b4]] +== Sending Patches with `b4` + +`b4` is a tool that builds on top of `git format-patch` and `git send-email`. +It automates much of the bookkeeping involved in sending a patch series to a +mailing-list-based project. + +Refer to the https://b4.docs.kernel.org/[b4 documentation] for a full reference. + +[[prep-b4]] +=== Preparing a Patch Series + +`b4` tracks your patch series as a branch. To start tracking the `psuh` branch +you have been working on, run: + +---- +$ b4 prep --enroll master +---- + +This enrolls the current branch, using `master` as the base of the topic. `b4` +manages the cover letter as part of the branch, so you can edit it at any time +with: + +---- +$ b4 prep --edit-cover +---- + +The cover letter not only tracks the content of the top-level mail, but also +the set of recipients. You can add recipients by adding `To:` and `Cc:` +trailer lines. + +[[send-b4]] +=== Sending the Patches + +Before sending the series out for real, you can inspect what `b4` would send by +passing `--dry-run`: + +---- +$ b4 send --dry-run +---- + +Once you are happy with the result, send the series with: + +---- +$ b4 send +---- + +[[v2-b4]] +=== Sending v2 + +When you are ready to send a new iteration of your series, refine your +patches as usual using linkgit:git-rebase[1]. Note that you typically want to +rebase on top of the cover letter. You can configure an alias to enable easy +rebases going forward: + +--- +$ git config set alias.b4-rebase 'rebase "HEAD^{/--- b4-submit-tracking ---}"' +$ git b4-rebase -i +--- + +Before sending out the new version you should also update the cover letter with +`b4 prep --edit-cover` to note the relevant changes compared to the previous +version. You can inspect the changes between the two versions with `b4 prep +--compare-to=v1`. + +Same as with the first version, you can use `b4 send` to send out the second +version. `b4` automatically bumps the version to `v2`, generates the range-diff +against the previous iteration, and threads the new series as a reply to the +cover letter of the first version. + +[[configure-b4]] +=== Configure b4 + +`b4` can be configured via linkgit:git-config[1]. In addition to that, projects +can have their own set of defaults in `.b4-config` in the root tree, which also +uses Git's config format. The user's configuration always takes precedence over +the per-project defaults. + +Refer to the https://b4.docs.kernel.org/en/latest/config.html[b4 config documentation] +for more information on the available options. + [[now-what]] == My Patch Got Emailed - Now What? diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index d570184ec8..99427e1ee1 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -573,8 +573,10 @@ your existing e-mail client (often optimized for "multipart/*" MIME type e-mails) might render your patches unusable. NOTE: Here we outline the procedure using `format-patch` and -`send-email`, but you can instead use GitGitGadget to send in your -patches (see link:MyFirstContribution.html[MyFirstContribution]). +`send-email`, but you can instead use GitGitGadget or `b4` to send in +your patches (see link:MyFirstContribution.html[MyFirstContribution]). +Contributors are encouraged to use `b4`, which automates much of the +bookkeeping that is otherwise done by hand. People on the Git mailing list need to be able to read and comment on the changes you are submitting. It is important for From 84b2ff7f2f708b8343d684ab57c72c1367de01e6 Mon Sep 17 00:00:00 2001 From: Patrick Steinhardt Date: Mon, 15 Jun 2026 14:59:43 +0200 Subject: [PATCH 3/3] b4: introduce configuration for the Git project In the preceding commit we have extended our documentation to recommend b4 for sending patch series to the mailing list. Introduce configuration so that it knows to honor preferences of the Git project by default. For now, this configuration does two things: - It configures "send-same-thread = shallow", which tells b4 to always send subsequent versions of the same patch series as a reply to the cover letter of the first version. - It configures "prep-cover-template", which tells b4 to use a custom template for the cover letter. The most important change compared to the default template is that our custom template also includes a range-diff. There's potentially more things that we may want to configure going forward, like for example auto-configuration of folks to Cc on certain patches. But these two tweaks feel like a good place to start. Note that these values only serve as defaults, and users may want to tweak those defaults based on their own preference. Luckily, users can do that without having to touch `.b4-config` at all, as b4 allows them to override values via Git configuration: ``` $ git config set b4.prep-cover-template /does/not/exist $ b4 send --dry-run ERROR: prep-cover-template says to use x, but it does not exist ``` So this gives users an easy way to override our defaults without having to touch ".b4-config", which would dirty the tree. Signed-off-by: Patrick Steinhardt Signed-off-by: Junio C Hamano --- .b4-config | 6 ++++++ .b4-cover-template | 11 +++++++++++ 2 files changed, 17 insertions(+) create mode 100644 .b4-config create mode 100644 .b4-cover-template diff --git a/.b4-config b/.b4-config new file mode 100644 index 0000000000..fd4fb56b6d --- /dev/null +++ b/.b4-config @@ -0,0 +1,6 @@ +# Note that these are default values that you can tweak via the typical +# git-config(1) machinery. You thus shouldn't ever have to change this file. +# See also https://b4.docs.kernel.org/en/latest/config.html. +[b4] +send-same-thread = shallow +prep-cover-template = ./.b4-cover-template diff --git a/.b4-cover-template b/.b4-cover-template new file mode 100644 index 0000000000..ab864933b5 --- /dev/null +++ b/.b4-cover-template @@ -0,0 +1,11 @@ +${cover} + +--- +${shortlog} + +${diffstat} + +${range_diff} +--- +base-commit: ${base_commit} +${prerequisites}