While b4 started out as a way for maintainers to retrieve patches from mailing lists, it also has contributor-oriented features. Starting with version 0.10 b4 can:
- create and manage patch series and cover letters
- track and auto-reroll series revisions
- display range-diffs between revisions
- apply trailers received from reviewers and maintainers
- submit patches without needing a valid SMTP gateway
These features are still considered experimental, but they should be stable for most work and I'd be happy to receive further feedback from occasional contributors.
In this article, we'll go through the process of submitting an actual typo fix patch to the upstream kernel. This bug was identified a few years ago and submitted via bugzilla, but never fixed:
Accompanying video
This article has an accompanying video where I go through all the steps and submit the actual patch at the end:
Installing the latest b4 version
Start by installing b4. The easiest is to do it via pip, as this would grab the latest stable version:
$ pip install --user b4
[...]
$ b4 --version
0.11.1
If you get an error or an older version of b4, please check that your $PATH contains $HOME/.local/bin where pip installs the binaries.
Preparing the tree
b4 prep -n [name-of-branch] -f [nearest-tag]
Next, prepare a topical branch where you will be doing your work. We'll be fixing a typo in arch/arm/boot/dts/aspeed-bmc-opp-lanyang.dts, and we'll base this work on tag v6.1:
$ b4 prep -n lanyang-dts-typo -f v6.1
Created new branch b4/lanyang-dts-typo
Created the default cover letter, you can edit with --edit-cover.
This is just a regular branch prepended with “b4/”:
$ git branch
* b4/lanyang-dts-typo
master
You can do all the normal operations with it, and the only special thing about it is that it has an “empty commit” at the start of the series containing the template of our cover letter.
Editing the cover letter
If you plan to submit a single patch, then the cover letter is not that necessary and will only be used to track the destination addresses and changelog entries. You can delete most of the template content and leave just the title and sign-off. The tracking information json will always be appended to the end automatically — you don't need to worry about it.
Here's what the commit looks like after I edited it:
$ git cat-file -p HEAD
tree c7c1b7db9ced3eba518cfc1f711e9d89f73f8667
parent 830b3c68c1fb1e9176028d02ef86f3cf76aa2476
author Konstantin Ryabitsev <icon@mricon.com> 1671656701 -0500
committer Konstantin Ryabitsev <icon@mricon.com> 1671656701 -0500
Simple typo fix for the lanyang dts
Signed-off-by: Konstantin Ryabitsev <icon@mricon.com>
--- b4-submit-tracking ---
# This section is used internally by b4 prep for tracking purposes.
{
"series": {
"revision": 1,
"change-id": "20221221-lanyang-dts-typo-8509e8ffccd4",
"base-branch": "master",
"prefixes": []
}
}
Committing your work
You can add commits to this branch as you normally would with any other git work. I am going to fix two obvious typos in a single file and make a single commit:
$ git show HEAD
commit 820ce2d9bc7c88e1515642cf3fc4005a52e4c490 (HEAD -> b4/lanyang-dts-typo)
Author: Konstantin Ryabitsev <icon@mricon.com>
Date: Wed Dec 21 16:17:21 2022 -0500
arm: lanyang: fix lable->label typo for lanyang dts
Fix an obvious spelling error in the dts file for Lanyang BMC.
This was reported via bugzilla a few years ago but never fixed.
Reported-by: Jens Schleusener <Jens.Schleusener@fossies.org>
Link: https://bugzilla.kernel.org/show_bug.cgi?id=205891
Signed-off-by: Konstantin Ryabitsev <icon@mricon.com>
diff --git a/arch/arm/boot/dts/aspeed-bmc-opp-lanyang.dts b/arch/arm/boot/dts/aspeed-bmc-opp-lanyang.dts
index c0847636f20b..e72e8ef5bff2 100644
--- a/arch/arm/boot/dts/aspeed-bmc-opp-lanyang.dts
+++ b/arch/arm/boot/dts/aspeed-bmc-opp-lanyang.dts
@@ -52,12 +52,12 @@ hdd_fault {
gpios = <&gpio ASPEED_GPIO(B, 3) GPIO_ACTIVE_HIGH>;
};
bmc_err {
- lable = "BMC_fault";
+ label = "BMC_fault";
gpios = <&gpio ASPEED_GPIO(H, 6) GPIO_ACTIVE_HIGH>;
};
sys_err {
- lable = "Sys_fault";
+ label = "Sys_fault";
gpios = <&gpio ASPEED_GPIO(H, 7) GPIO_ACTIVE_HIGH>;
};
};
Collecting To: and Cc: addresses
After you've committed your work, you will want to collect the addresses of people who should be the ones reviewing it. Running b4 prep --auto-to-cc will invoke scripts/get_maintainer.pl with the default recommended flags to find out who should go into the To: and Cc: headers:
$ b4 prep --auto-to-cc
Will collect To: addresses using get_maintainer.pl
Will collect Cc: addresses using get_maintainer.pl
Collecting To/Cc addresses
+ To: Rob Herring <...>
+ To: Krzysztof Kozlowski <...>
+ To: Joel Stanley <...>
+ To: Andrew Jeffery <...>
+ Cc: devicetree@vger.kernel.org
+ Cc: linux-arm-kernel@lists.infradead.org
+ Cc: linux-aspeed@lists.ozlabs.org
+ Cc: linux-kernel@vger.kernel.org
+ Cc: Jens Schleusener <...>
---
You can trim/expand this list with: b4 prep --edit-cover
Invoking git-filter-repo to update the cover letter.
New history written in 0.06 seconds...
Completely finished after 0.33 seconds.
These addresses will be added to the cover letter and you can edit them to add/remove destinations using the usual b4 prep --edit-cover command.
Creating your patatt keypair for web endpoint submission
(This needs to be done only once.)
Note: if you already have a PGP key and it's set as user.signingKey, then you can skip this section entirely.
Before we submit the patch, let's set up the keypair to sign our contributions. This is not strictly necessary if you are going to be using your own SMTP server to submit the patches, but it's a required step if you will use the kernel.org patch submission endpoint (which is what b4 will use in the absence of any [sendemail] sections in your git config).
The process is very simple. Run patatt genkey and add the resulting [patatt] section to your ~/.gitconfig as instructed by the output.
NOTE: You will want to back up the contents of your ~/.local/share/patatt so you don't lose access to your private key.
Dry-run and checkpatch
b4 send -o /tmp/tosend./scripts/checkpatch.pl /tmp/tosend/*
Next, generate the patches and look at their contents to make sure that everything is looking sane. Good things to check are:
- the From: address
- the To: and Cc: addresses
- general patch formatting
- cover letter formatting (if more than 1 patch in the series)
If everything looks sane, one more recommended step is to run checkpatch.pl from the top of the kernel tree:
$ ./scripts/checkpatch.pl /tmp/tosend/*
total: 0 errors, 0 warnings, 14 lines checked
/tmp/tosend/0001-arm-lanyang-fix-lable-label-typo-for-lanyang-dts.eml has no obvious style problems and is ready for submission.
Register your key with the web submission endpoint
(This needs to be done only once, unless you change your keys.)
b4 send --web-auth-newb4 send --web-auth-verify [challenge]
If you're not going to use your own SMTP server to send the patch, you should register your new keypair with the endpoint:
$ b4 send --web-auth-new
Will submit a new email authorization request to:
Endpoint: https://lkml.kernel.org/_b4_submit
Name: Konstantin Ryabitsev
Identity: icon@mricon.com
Selector: 20221221
Pubkey: ed25519:24L8+ejW6PwbTbrJ/uT8HmSM8XkvGGtjTZ6NftSSI6I=
---
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 icon@mricon.com
Once you receive it, run b4 send --web-auth-verify [challenge-string]
The challenge is a UUID4 string and this step is a simple verification that you are able to receive email at the address you want associated with this key. Once you receive the challenge, complete the process as described:
$ b4 send --web-auth-verify 897851db-9b84-4117-9d82-1d970f9df5f8
Signing challenge
Submitting verification to https://lkml.kernel.org/_b4_submit
---
Challenge successfully verified for icon@mricon.com
You may now use this endpoint for submitting patches.
OR, set up your [sendemail] section
You don't have to use the web endpoint — it exists primarily for people who are not able or not willing to set up their SMTP information with git. Setting up a SMTP gateway is not a straightforward process for many:
- platforms using OAuth require setting up “application-specific passwords”
- some companies only provide Exchange or browser-based access to email and don't offer any other way to send mail
- some company SMTP gateways rewrite messages to add lengthy disclaimers or rewrite links to quarantine them
However, if you have access to a functional SMTP gateway, then you are encouraged to use it instead of submitting via the web endpoint, as this ensures that the development process remains distributed and not dependent on any central services. Just follow instructions in man git-send-email and add a valid [sendemail] section to your git config. If b4 finds it, it will use it instead of relying on the web endpoint.
[sendemail]
smtpEncryption = tls
smtpServer = smtp.gmail.com
smtpServerPort = 465
smtpEncryption = ssl
smtpUser = yourname@gmail.com
smtpPass = your-gmail-app-password
Reflect the email to yourself
This is the last step to use before sending off your contribution. Note, that it will fill out the To: and Cc: headers of all messages with actual recipients, but it will NOT actually send mail to them, just to yourself. Mail servers don't actually pay any attention to those headers — the only thing that matters to them is what was specified in the RCPT TO outer envelope of the negotiation.
This step is particularly useful if you're going to send your patches via the web endpoint. Unless your email address is from one of the following domains, the From: header will be rewritten in order to not violate DMARC policies:
- @kernel.org
- @linuxfoundation.org
- @linux.dev
If your email domain doesn't match the above, the From: header will be rewritten to be a kernel.org dummy address. Your actual From: will be added to the body of the message where git expects to find it, and the Reply-To: header will be set so anyone replying to your message will be sending it to the right place.
Send it off!
If all your tests are looking good, then you are ready to send your work. Fire off “b4 send”, review the “Ready to:” section for one final check and either Ctrl-C to get out of it, or hit Enter to submit your work upstream.
Coming up next
In the next post, I will go over:
- making changes to your patches using:
git rebase -i
- retrieving and applying follow-up trailers using:
b4 trailers -u
- comparing v2 and v1 to see what changes you made using:
b4 prep --compare-to v1
- adding changelog entries using:
b4 prep --edit-cover
Documentation
All contributor-oriented features of b4 are documented on the following site:
