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

Note

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

Note

Creating a new ed25519 key is not required if you already have a PGP key configured with git using the user.signingKey git-config setting.

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

Copy the [patatt] section and add it to your ~/.gitconfig or to your .git/config in the repository that you want to enable for b4 send.

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 ~/.gitconfig:

[b4]
  send-endpoint-web = https://lkml.kernel.org/_b4_submit

Note

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: alice.developer@example.org
  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 alice.developer@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 confirmation message:

$ 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 alice.developer@example.org
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

B4 will use the sendemail section from your git configuration, but it only supports the most common subset of options. The vast majority of servers will only need the following settings:

[sendemail]
   smtpServer = smtp.example.org
   smtpPort = 465
   smtpEncryption = ssl
   smtpUser = alice.developer@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.

Sending your patches

Once your web endpoint or SMTP server are configured, you can start sending your work.

Note

At this time, only series prepared with b4 prep are supported, but future versions may support sending arbitrary patches generated with git format-patch.

Checking things over with -o

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 --reflect

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.

When --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 v1 of the series, the working version will be marked as v2

  • 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

-d, --dry-run

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 instead.

-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.

--reflect (v0.11+)

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.

--no-trailer-to-cc

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 --reflect).

--hide-cover-to-cc

It is common for the To: and Cc: sections in cover letters to be pretty large on large patch sets. Passing this flag will remove these trailers from the cover letter, but still add the addresses to the corresponding To: and Cc: headers. This can be made permanent in the configuration file using the b4.send-hide-cover-to-cc option (see Contributor-oriented settings).

--to

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-to option (see Contributor-oriented settings).

--cc

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-cc option (see Contributor-oriented settings).

--not-me-too

Removes your own email address from the recipients.

--no-sign

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 -o or 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 V

Resend a previously sent version (see above for more info).