send: sending in your work

B4 supports sending your series either via your own SMTP-compliant mail server, or via a web submission endpoint.

Upsides of using your own mail server:

it’s 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 rewrite the From: headers in patches, which is required for email delivery that originates at a different domain

However, using your own mail server may not always be a valid option:

your provider may not offer an SMTP-compliant endpoint for sending mail; for example it may only provide a webmail/exchange interface
there may be limits on the number of messages you can send through your mail server in a short period of time, which makes it hard to send large patch series
your company mail 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 endpoint writes all messages to a public-inbox feed and makes them 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 by mail relays

Note

Even if you opt to use the web submission endpoint, you still need a valid email account for participating in decentralized development – it’s required for taking part in discussions and for sending and receiving code review feedback.

Authenticating with the web submission endpoint

Before you start, you 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 isn’t 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

Which web endpoint to use is going to be dependent on the project. For the Linux kernel and associated tools (like Git, B4, patatt, etc), you can use the kernel.org endpoint by adding the following to your ~/.gitconfig:

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

Note

You can only use the kernel.org endpoint for kernel.org-hosted projects. If there are no recognized mailing lists in the to/cc headers, the endpoint refuses to accept the submission.

After updating your git configuration file, 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 confirmation string from the 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

If there is a sendmail section in your git configuration, B4 tries to use that by default instead of going via the web endpoint. At this time, b4 only recognizes a subset of sendmail options supported by git itself. The vast majority of servers should only need the following settings:

[sendemail]
   smtpServer = smtp.example.org
   smtpServerPort = 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. To force B4 to use the web endpoint even when a sendmail option is present, use the --use-web-endpoint switch.

Sending your patches

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

Note

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

Passing pre-flight checks (v0.14+)

B4 defines some pre-flight checks that should be passing, or the command generates a warning:

needs-editing: there is an “EDITME” string in the patches generated, which usually indicates that the cover letter needs to be edited with b4 prep --edit-cover
needs-checking: you need to run b4 prep --check to make sure that there are no common errors in your submission
needs-checking-deps: your series defines dependencies, and you need to run b4 prep --check-deps to verify that they are valid (see prep: preparing your patch series)
needs-auto-to-cc: you need to run b4 prep --auto-to-cc to populate the list of addresses that should receive your patch series

If you find that some of these pre-flight checks aren’t relevant to you, you can either turn them all off, or only the ones that you don’t like. To do so, use the prep-pre-flight-checks configuration option, for example:

[b4]
prep-pre-flight-checks = disable-all

or:

[b4]
prep-pre-flight-checks = disable-needs-auto-to-cc, disable-needs-checking

B4 automatically recognizes when your commits have changed and triggers the pre-flight checks warning when it thinks that you should re-run them.

Checking things over with `-o`

Before you send things out, it’s a good idea to verify that everything is looking good by running the send command with -o somedir, e.g.:

b4 send -o /tmp/presend

This generates the messages and writes them out into the directory provided, giving you a way to verify that everything is looking as it should before sending.

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 are going to look like after being potentially post-processed on the remote end.

When --reflect is on:

b4 still populates the To:/Cc: headers with all the addresses, because this allows to identify any encoding problems
b4 only sends the series to the address in the From: field
when using the web endpoint, the messages aren’t added to the public-inbox feed
your branch is not automatically rerolled to the next revision

Checking things over with `--preview-to` (v0.13+)

Sometimes you want to ask your friend, colleague, boss, or mentor to give your submission a quick review. You can send them your series using --preview-to boss@example.com before you send things out to the actual maintainers.

When --preview-to is on:

b4 only sends to the addresses you specify on the command line
your branch is not automatically rerolled to the next revision

(NB: the web submission endpoint can’t currently be used with this feature.)

What happens after you send

The following happens after you send your patches:

b4 automatically creates a detached head containing the commits from your sent series and tags 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, should you decide to do so in the future
b4 rerolls your series to the next version, so that a v1 of the series becomes v2, etc
b4 automatically edits the cover letter to add 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’s easy to do this with --resend vN. B4 automatically generates the series from the tagged historical version created during the previous sending attempt and sends it out.

Command line flags

-d, --dry-run: Don’t send any mail, just output the raw pre-rendered messages. 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 step before actually sending things out and lets you verify that all patches are looking good and all recipients are correctly set.
--preview-to (v0.13+): Sometimes it’s useful to send your series for a pre-review to a colleague, mentor, boss, etc. Using this option sends out the prepared patches to the addresses specified on the command line, but doesn’t reroll your series, allowing you to send the actual submission at some later point.
--reflect (v0.11+): Prepares everything for sending, but only emails yourself (the address in the From: header). Useful as a last step 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: Tells b4 not to 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).
--to: Additional email addresses to include into the To: header. Separate multiple entries with a comma. You can also set this in the configuration file using the b4.send-series-to option (see Contributor-oriented settings).
--cc: Additional email addresses to include into the Cc: header. Separate multiple entries with a comma. You can also set this 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 sending via the web submission endpoint requires cryptographic signatures at all times, 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 the specified previously sent version.

send: sending in your work

Authenticating with the web submission endpoint

Creating a new ed25519 key

Configuring the web endpoint

Using your own SMTP server

Sending your patches

Passing pre-flight checks (v0.14+)

Checking things over with -o

Checking things over with --reflect

Checking things over with --preview-to (v0.13+)

What happens after you send

Resending your series

Command line flags

Checking things over with `-o`

Checking things over with `--reflect`

Checking things over with `--preview-to` (v0.13+)