Congratulations! You just finished developing your first contribution to the Linux kernel, and are excited to submit it. The process for doing so is tricky, with many conventions that the community has developed over time, so here is what I learned after doing so for the first time. This is intended to be a succinct supplement to the official contribution documentation.

Overview

The contribution process operates via email. You can technically send a patch using a normal email client, but I recommend using using git send-email instead. git send-email will automatically take care of the formatting conventions (“[PATCH]” subject prefix, “Signed-off-by:” tag, --- separator, appending the patch contents to the end), and is much less error prone. That said, there are a number of subtleties to the process that do require close attention.

Preparing your patch

First, squash your contribution into a single git commit¹ based off a well-known release point (a stable or rc tag on Linus’ tree). Writing the commit message properly is extremely important, and one of the few parts of this process where the conventions are not handled by automated tools.

For the first line, make sure you follow the standard “subsystem: summary” format where the message is prefixed with an informal description of the subsystem, followed by a colon. I say “informal” because the subsystem part doesn’t need to strictly follow the directory layout. For example, here is a commit where the subsystem is noted as “x86/defconfigs” but the file modified is arch/x86/configs/i386_defconfig. Don’t forget to use the present tense for writing the summary.

For the commit message body, make sure you follow the guidance here. Don’t forget to wrap at 75 characters². Don’t worry about typing the “Signed-off-by” tag in your commit message. git send-email will take care of that for you.

Here’s how my patch looked:

Sending your patch

Who do I send the patch to?

Once you have finished your commit, you’re ready to send it to the maintainers of the relevant subsystem or files. You can look up this information using the scripts/get_maintainer.pl script within the kernel tree.

Create a patch file by piping your commit diff to disk, then run the get_maintainer.pl script on that file.

That will print out the people you can send the patch to. Don’t worry about sending it to too many people — the kernel maintainers would rather you do that, than send to too few.

When mailing patches, it is important to send copies to anybody who might be interested in it. Unlike some other projects, the kernel encourages people to err on the side of sending too many copies; don’t assume that the relevant people will see your posting on the mailing lists.

https://www.kernel.org/doc/html/v4.16/process/5.Posting.html#sending-the-patch

Sending the patch

Now you’re ready to use git send-email to send the patch. git send-email does not come with a standard git installation, so you need to install it separately.

apt install git-email

Next, you’ll need to set git send-email up with your email account. If you use Gmail and have two-factor authentication enabled, it’s very easy. (Instructions taken from here)

1. Generate an app specific password
2. Store it in your git config

git config --global sendemail.smtpPass 'your password'

Now you’re ready to send your patch.

The syntax of a git send-email command looks like this:

git send-email HEAD^ -s --to=person@email.com --cc=person2@email.com

• -s : This will automatically include the “Signed-off-by” line, using the information in your git config³
• --to and --cc specify the To: and CC: fields of the email. You can use them multiple times, or use commas to delineate multiple recipients.

When git send-email asks if you’re ready to send, you can type “e” to see what it generated:

Again, note that it automatically takes care of all of the formatting like the “[PATCH]” prefix, “Signed-off-by” tag, --- delimiter, and appending the patch. This formatting is specified in “The canonical patch format” section of the docs. An excerpt:

The canonical patch message body contains the following:

• A from line specifying the patch author, followed by an empty line (only needed if the person sending the patch is not the author).
• The body of the explanation, line wrapped at 75 columns, which will be copied to the permanent changelog to describe this patch.
• An empty line.
• The Signed-off-by: lines, described above, which will also go in the changelog.
• A marker line containing simply ---.
• Any additional comments not suitable for the changelog.
• The actual patch (diff output).

All that’s left to do is type “yes” and git send-email will send your patch for review. Congratulations, you just submitted a patch to the Linux kernel!

Discussing your patch

You will likely need to discuss with the maintainers about your patch. You can do this using Gmail — just remember to select “Plain text mode” in the message compose settings, and use the “inline reply” convention where you reply at the bottom of the email vs the top.

Conclusion

Contributing a patch to the Linux kernel is an arcane process, requiring you to adhere to many esoteric conventions that have been developed by the community over time. While many conventions are handled automatically, there are key pieces that aren’t, like writing the commit message. While it’s unfortunate that the barrier to contribution is so high, there are valid reasons⁴ for this method of operation, and I hope this guide is useful to those navigating this process for the first time.

1. I’m assuming you’re not doing a complicated, multi-patch series for your first contribution!
2. https://www.kernel.org/doc/html/v4.16/process/submitting-patches.html#the-canonical-patch-format
3. You can set format.signOff in your git config to enable this automatically.
4. See this twitter thread for more on this.