send: sending in your work
B4 supports sending your series either via your own SMTP server, or via a web submission endpoint.
Upsides of using your own SMTP server:
it is part of decentralized infrastructure not dependent on a single point of failure
it adds domain-level attestation to your messages via DKIM signatures
it avoids the need to munge the From: headers in patches, which is required for email delivery that originates at a different domain
However, using your own SMTP server may not always be a valid option:
your mail provider may not offer an SMTP compliant server for sending mail (e.g. if it only uses a webmail/exchange client)
there may be limits on the number of messages you can send through your SMTP server in a short period of time (which is normal for large patch series)
your company SMTP server may modify the message bodies by adding huge legal disclaimers to all outgoing mail
The web submission endpoint helps with such cases, plus offers several other upsides:
the messages are written to a public-inbox feed, which is then immediately available for others to follow and query
all patches are end-to-end attested with the developer signature
messages are less likely to get lost or delayed
Even if you opt to use the web submission endpoint, you still need a valid email account for participating in decentralized development – you will need it to take part in discussions and for sending and receiving code review feedback.
Authenticating with the web submission endpoint
Before you start, you will need to configure your attestation mechanism. If you already have a PGP key configured for use with git, you can just use that and skip the next section. If you don’t already have a PGP key, you can create a separate ed25519 key just for web submission purposes.
Creating a new ed25519 key
Creating a new ed25519 key is not required if you already have a PGP
key configured with git using the
Installing b4 should have already pulled in the patatt patch attestation library. You can use the command line tool to create your ed25519 key:
$ patatt genkey Generating a new ed25519 keypair Wrote: /home/user/.local/share/patatt/private/20220915.key Wrote: /home/user/.local/share/patatt/public/20220915.pub Wrote: /home/user/.local/share/patatt/public/ed25519/example.org/alice.developer/20220915 Add the following to your .git/config (or global ~/.gitconfig): --- [patatt] signingkey = ed25519:20220915 selector = 20220915 --- Next, communicate the contents of the following file to the repository keyring maintainers for inclusion into the project: /home/user/.local/share/patatt/public/20220915.pub
[patatt] section and add it to your
~/.gitconfig or to
.git/config in the repository that you want to enable for
Configuring the web endpoint
The web endpoint you will use is going to be dependent on the project.
For the Linux kernel and associated tools (like Git, B4, patatt, etc),
the kernel.org endpoint can be enabled by adding the following to your
[b4] send-endpoint-web = https://lkml.kernel.org/_b4_submit
The kernel.org endpoint can only be used for kernel.org-hosted projects. If there are no recognized mailing lists in the to/cc headers, then the submission will be rejected.
Once that is added, you can request authentication, as in the example below:
$ b4 send --web-auth-new Will submit a new email authorization request to: Endpoint: https://lkml.kernel.org/_b4_submit Name: Alice Developer Identity: email@example.com Selector: 20220915 Pubkey: ed25519:ABCDE1lNXHvHOTuHV+Cf1eK9SuRNZZYrQmcJ44IkE8Q= --- 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 firstname.lastname@example.org Once you receive it, run b4 send --web-auth-verify [challenge-string]
As the instructions say, you should receive a verification email to the
address you specified in your
user.email. Once you have received it,
run the verification command by copy-pasting the UUID from the
$ b4 send --web-auth-verify abcd9b34-2ecf-4d25-946a-0631c414227e Signing challenge Submitting verification to https://lkml.kernel.org/_b4_submit --- Challenge successfully verified for email@example.com You may now use this endpoint for submitting patches.
You should now be able to send patches via this web submission endpoint.
Using your own SMTP server
If there is a
sendmail section in your git configuration, B4 will try use
that by default instead of the web endpoint. Only the most common subset of
options are supported. The vast majority of servers will only need the
[sendemail] smtpServer = smtp.example.org smtpServerPort = 465 smtpEncryption = ssl smtpUser = firstname.lastname@example.org smtpPass = [omitted]
You can also set up msmtp or a similar tool and specify the path to the
sendmail-compliant binary as the value for
smtpServer. You can force B4
to use the web endpoint by using the
Sending your patches
Once your web endpoint or SMTP server are configured, you can start sending your work.
At this time, only series prepared with
b4 prep are supported, but
future versions may support sending arbitrary patches generated with
Checking things over with
It is a good idea to first check that everything is looking good by
running the send command with
-o somedir, e.g.:
b4 send -o /tmp/presend
This will write out the messages just as they would be sent out, giving you a way to check that everything is looking as it should.
Checking things over with
One final test you can do before you submit your series is to send everything to yourself. This is especially useful when using the web endpoint, because this allows you to see what the messages will look like after being potentially post-processed on the remote end.
--reflect is on:
b4 will still populate the To:/Cc: headers with all the addresses, because this allows to check for any encoding problems
b4 will only send the series to the address in the From: field
when using the web endpoint, the messages will not be added to the public-inbox feed
your branch will not be automatically rerolled to the next revision
What happens after you send
The following happens after you send your patches:
b4 will automatically create a detached head containing the commits from your sent series and tag it with the contents of the cover letter; this creates a historical record of your submission, as well as adds a way to easily resend a previously sent series
b4 will reroll your series to the next version, so that if you just sent off a
v1of the series, the working version will be marked as
b4 will automatically edit the cover letter to add templated changelog entries containing a pre-populated link to the just-sent series
Resending your series
If something went wrong, or if you need to resend the series because
nobody paid attention to it the first time, it is easy to do this with
--resend vN. B4 will automatically generate the series from the
tagged historical version created during the previous sending attempt.
Command line flags
Don’t send any mail, just output the raw messages that would be sent. Normally, this is a wall of text, so you’d want to use
-o OUTPUT_DIR, --output-dir OUTPUT_DIR
Prepares everything for sending, but writes out the messages into the folder specified instead. This is usually a good last check before actually sending things out and lets you verify that all patches are looking good and all recipients are correctly set.
Prepares everything for sending, but only emails yourself (the address in the
From:header). Useful as a last check to make sure that everything is looking good, and especially useful when using the web endpoint, because it may rewrite your From: header for DMARC reasons.
Do not add any addresses found in the cover or patch trailers to To: or Cc:. This is usually handy for testing purposes, in case you want to send a set of patches to a test address (also see
Add any more email addresses to include into the To: header here (comma-separated). Can be set in the configuration file using the
b4.send-series-tooption (see Contributor-oriented settings).
Add any more email addresses to include into the Cc: header here (comma-separated). Can be set in the configuration file using the
b4.send-series-ccoption (see Contributor-oriented settings).
Removes your own email address from the recipients.
Don’t sign your patches with your configured attestation mechanism. Note, that patch signing is required for the web submission endpoint, so this is only a valid option to use with
-oor when using your own SMTP server. This can be set in the configuration using the
b4.send-no-patatt-sign(see Contributor-oriented settings).
Resend a previously sent version (see above for more info).