b4 Tool for Code Contributors
The b4 tool offers features that simplify the process for code contributors submitting patches. Currently, it is increasingly utilized in the Linux kernel development workflow.
You can install b4 tool in the Debian based Linux systems with the following command:
1
sudo apt install b4
Below are the commands illustrating the development workflow for developers.
b4 prep
Creating separate work branch
b4 assumes that you create a new branch before starting to work on a patch (series). To create a branch for your work:
1
b4 prep -n <patch_series_name>
You can also create a branch from a specific commit ID.
1
b4 prep -n <patch_series_name> -f <commit_id>
These commands create a new branch and checkout to newly created branch automatically. Now, as usual, you modify and create commits using standard Git commands like git add, git commit, git commit --amend, etc.
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
If your project lacks a MAINTAINERS file or any b4 configuration at its core, you may not find a list of recipient emails from the above command. In that case, refer to the last section.
Set the email subject prefixes
You may want to add a prefix such as RFC or RESEND to the email subject. Use the following command to set the prefix. By default, b4 prep adds the prefixes PATCH and a version number such as v2 or v3. These default prefixes cannot be removed.”
1
b4 prep --set-prefixes "RFC RESEND"
You can reset the prefixes with:
1
b4 prep --set-prefixes ""
b4 send
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
# 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
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
Once b4 has sent patch v1 to the list, it increments the current version number by 1, and you can continue working on the patch based on the received review comments. As usual, modify the files, use commands like git add, git commit –amend, etc. Now, run b4 prep --edit-cover again to write the changes in the current version. b4 maintains a template for changes in the current version and also remembers the version changes history, so you don’t have to copy-paste every time you send a new iteration of the patch. Verify the patch, once ready resend it using b4 send.
If, for some reason, you want to resend the same patch, you can do so without incrementing the version number by using the following command with b4.
1
b4 send --resend v2 # v<version_number>
b4 trailers
If someone has provided a Reviewed-by or Acked-by or any other tag, you can gather all those trailers into your commit using the following command:
1
b4 trailers -u
This command is applicable only when the project utilizes an archived mailing list service such as https://lore.kernel.org/. It retrieves trailers from the archive.
Some popular projects leveraging this service include Linux, Buildroot, and certain Yocto meta layers.
Cleaning up
After your patch is merged into the upstream, you can delete the development branch with:
1
b4 prep --cleanup <branch_name>
A simple b4 config file
Here is a sample .b4-config file that can be placed in the root directory of your project. This example utilizes the Gmail SMTP server to send patches using b4.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
[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