b4 Tool for Code Contributors
The b4 tool streamlines the patch submission process for code contributors, and it is gaining popularity in the Linux kernel development workflow.
To get the latest version of the b4 tool, use the commands below, since the version available in your Linux distribution’s software center might be outdated:
1
2
3
sudo apt install pipx # For Debian based Linux systems
pipx ensurepath
pipx install b4
This guide applies to b4 version v0.14 or later. Verify your version by running b4 --version.
Here are the commands demonstrating the development workflow for contributors.
b4 prep
Creating a topic branch
It’s assumed that you will create a topic branch before beginning work on a patch series. Below are various methods to establish a topic branch:
- To initiate a topic branch from the latest commit of the current branch, execute:
1
b4 prep -n <patch_series_name> - To create a topic branch from a specific commit, run:
1
b4 prep -n <patch_series_name> -f <commit_id>
- To enroll an existing branch with commits into b4, execute:
1
b4 prep -e <branch_name> - If you’ve previously submitted a patch series using
git send-email, you can prepare a new branch for the next version of the patch series with the following command:1
b4 prep -n <branch_name> -F <Message-ID>
Locate the Message-ID of your previous patch series by searching for it on public-inbox platforms like https://lore.kernel.org.
The commands above create and automatically switch to a new branch. You can then proceed to modify files and create commits using typical Git commands such as git add, git commit, and git commit --amend.
Mentioning Dependency Patch (Series)
You may need to reference a patch (or series) that hasn’t yet been merged, on which your patch is dependent, in the commit message or cover letter. To do so, include the change-id of the relevant patch (or series) using this command:
1
b4 prep --edit-deps
Provide the change-id followed by the dependent patch version, formatted as shown below.
1
change-id: 20240402-b4-dts_dxl_audio-74ba02030a72:v5
Observe that the dependency patch version v5 is appended to the change-id.
The above is taken from https://lore.kernel.org/lkml/20240425-b4-dts_dxl_audio-v5-0-46397f23ce35@nxp.com/:
To see if new versions of your dependency patches are available, run:
1
b4 prep --check-deps
This step confirms that the base commit is present in the tree and that both the dependency patches and your patches apply without conflicts.
Preparing the cover letter
The following command can be used to prepare the cover letter. For single commit submissions, you can simply delete the first line that starts with EDITME.
1
b4 prep --edit-cover
This command can also be utilized to edit the list of recipients for the patch series. See the next section for details.
Retrieve recipients’ email addresses
Linux kernel developers used to execute the script get_maintainer.pl against the patch to retrieve the recipients’ email addresses to which the patch needs to be sent. Then, they would manually use these email addresses as arguments to the git send-email command to send the patches to the list. The following command simplifies the process of gathering the relevant addresses from the commits themselves.
1
b4 prep --auto-to-cc
Without a MAINTAINERS file or b4 configuration containing recipient email addresses, the command may not yield a list of recipient emails.
Set the email subject prefixes
You might want to add a prefix like RFC or RESEND to the email subject. Use the command below to set your desired prefix. Note that b4 prep automatically includes PATCH and a version number like v2 or v3. These default prefixes cannot be omitted.
1
b4 prep --set-prefixes "RFC RESEND"
To append the prefixes to existing ones, run:
1
b4 prep --add-prefies "WIP"
You can reset the prefixes with:
1
b4 prep --set-prefixes ""
Run basic checks
1
br prep --check
This runs the scripts/checkpatch.pl script, check for spelling errors, and verify the presence of trailers like Signed-off.
b4 send
There are two ways to send the patches to the mailing list using the b4 tool:
- Send the patches through a web endpoint.
- Send the patches through an SMTP mail server.
Sending patches via web endpoint
A web endpoint is a URL that processes incoming data. For projects hosted on kernel.org, the web endpoint used is https://lkml.kernel.org/_b4_submit.
Sending patches via a web endpoint has the advantage of eliminating concerns about patches being altered or corrupted by the mail server. Setting up PGP key is mandatory to send patches via this method.
Add the following configuration to your project’s .b4-config file:
1
2
[b4]
send-endpoint-web = https://lkml.kernel.org/_b4_submit
Then, in the project directory, execute this command to set the user signing key for use with b4 and git:
1
git config user.signingKey [fingerprint]
Web Authentication and Verification
You must authenticate your PGP key first before sending patches. This is a one-time setup. To authenticate, execute the following command:
1
b4 send --web-auth-new
The output looks similar to this:
1
2
3
4
5
6
7
8
9
10
11
12
Will submit a new email authorization request to:
Endpoint: https://lkml.kernel.org/_b4_submit
Name: Nayab Sayed
Identity: nayab@example.com
Selector: default
Pubkey: openpgp:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
---
Press Enter to confirm or Ctrl-C to abort
Submitting new auth request to https://lkml.kernel.org/_b4_submit
---
Challenge generated and sent to nayab@example.com
Once you receive it, run b4 send --web-auth-verify [challenge-string]
Enter when prompted and you will receive an e-mail with the challenge-string. Once you received the challenge-string, run the following command for the verificationt to complete.
1
b4 send --web-auth-verify <challenge-string>
Here is an example:
1
b4 send --web-auth-verify 5f989f08-e1b3-4022-a609-029808d66899
Override SMTP config, if set already.
If an SMTP mail server configuration is detected in either the git or b4 configuration files, the b4 tool will send patches via SMTP instead of using a web endpoint. To override the SMTP config, use the option --use-web-endpoint. Don’t forget to verify the patch before sending.
1
b4 send --use-web-endpoint
Here is an example .b4-config for web endpoint method
1
2
3
4
5
6
7
8
9
[b4]
prep-cover-strategy = branch-description
send-no-patatt-sign = yes
send-endpoint-web = https://lkml.kernel.org/_b4_submit
# If your project doesn't have MAINTAINERS file, use send-series-to or
# send-series-cc to add recipients email or list address
send-series-to = <e-mail_id>
send-series-cc = <e-mail_id>
Sending patches via SMTP server
This is the default method b4 uses to send patches. Here is an example .b4-config for SMTP mail server method.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
[b4]
prep-cover-strategy = branch-description
send-no-patatt-sign = yes
# If your project doesn't have MAINTAINERS file, use send-series-to or
# send-series-cc to add recipients email or list address
send-series-to = <e-mail_id>
send-series-cc = <e-mail_id>
[sendemail]
smtpServer = smtp.gmail.com
smtpServerPort = 587
smtpEncryption = tls
smtpUser = <gmail_id>
smtpPass = appPassword
Verify the patch before sending
Here are a few commands you can try to verify before sending the patch to the list.
1
2
3
4
5
6
7
8
# Writes raw messages to /tmp/presend directory.
b4 send -o /tmp/presend
# Send the patch only to yourself. The the e-mail looks like as if you sent to the actual list of recipients.
b4 send --reflect
# Send the patch to the email (or grop alias) specified for a quick review by peers.
b4 send --preview-to <internal_group_alias_mail>
Sending the patch
Execute the following command to send the patch to the list.
1
b4 send
Addressing review comments and sending the next patch version
After b4 dispatches the initial version (v1) of the patch to the list, it automatically increments the version number. This allows you to seamlessly continue working on the patch for the next version in response to any feedback.
Once the changes are done, execute b4 prep --edit-cover to document the modifications made since the last version. With b4, a template is maintained for the current version’s changes and the history of version changes is tracked, eliminating the need for manual copy-pasting when submitting new iterations.
Once you’ve verified the patch, proceed to send the updated version using b4 send.
To resend an identical patch without changing the version number, use the following b4 command.
1
b4 send --resend v2 # v<version_number>
b4 trailers
To collect all the trailers such as Reviewed-by, Acked-by, or others given in response to your patch in the mainline, use the following command:
1
b4 trailers -u
This command applies when a project uses an archived mailing list service, like https://lore.kernel.org/, to gather trailers from the archive.
Popular projects using this service include Linux, Buildroot, and various Yocto meta layers.
Cleaning up
Once your patch is integrated into the mainline, you can remove the development branch by using:
1
b4 prep --cleanup <branch_name>