Submitting your first patch to the Linux kernel

Linux kernel development is done by mailing lists. You have just improved a piece of code or documentation. What now? In this post, I will show you how to submit a patch to the Linux kernel, as well as some tips I learned.

Introduction

There are many ways one can contribute to Linux development. You could improve documentation, write a new driver or module, improve existing code, etc. This is not a tutorial about how to write code for the kernel, I suppose you already know how to code and want an easy to follow guide about how to submit your diffs. Let’s get started!

Cloning the current source tree and configuring Git

Setting up an email client

You will need an email client to send your diffs. I will configure mutt with Gmail:

1. Activate the less secure apps access to your Google account;


2. In Gmail, click on the gear icon and go to “Settings”. Then, go to the tab “Forwarding POP/IMAP”, click on “Enable IMAP” and save the changes;


3. Install mutt:
   $ sudo apt install mutt # For Debian and derivatives
$ sudo dnf install mutt # For Fedora and Red Hat derivatives


4. Now you need to configure mutt. I use the following config in the ~/.mutt/muttrc file (replace the fields with your information):
   set ssl_starttls=yes
set ssl_force_tls=yes
set imap_user = "YOUR_EMAIL"
set imap_pass = "YOUR_PASSWD"
set from="YOUR_EMAIL"
set realname="FIRST_NAME LAST_NAME"
set folder = "imaps://imap.gmail.com/"
set spoolfile = "imaps://imap.gmail.com/INBOX"
set postponed="imaps://imap.gmail.com/[Gmail]/Drafts"
set header_cache = "~/.mutt/cache/headers"
set message_cachedir = "~/.mutt/cache/bodies"
set certificate_file = "~/.mutt/certificates"
set smtp_url = "smtps://YOUR_EMAIL:YOUR_PASSWD@smtp.gmail.com:465/"
set record="~/mail/sent"
set move = no
set imap_keepalive = 900


5. Run mutt on terminal to check if your email client is working.

Submitting a patch

It is time to finally send your diff to the maintainers. I will make a small change in a documentation page (just an example, it won’t be sent):

1. Check your changes:
   $ git status


2. Add and commit your changes:
   $ git add Documentation/index.rst
$ git commit -s -v

   An editor with your diff will appear. Write a clear comment. For example:
   docs: Correct grammar errors.


3. Generate a patch file:
   $ git format-patch -o /tmp HEAD^


4. Run the checkpatch script before submitting (it will tell you potential issues):
   $ ./scripts/checkpatch.pl /tmp/patch_name.patch


5. Figure out where to send your patch:
   $ ./scripts/get_maintainer.pl /tmp/patch_name.patch
Jonathan Corbet (maintainer:DOCUMENTATION)
linux-doc@vger.kernel.org (open list:DOCUMENTATION)
linux-kernel@vger.kernel.org (open list)


6. Send your patch:
   $ mutt -H /tmp/patch_name.patch

   The patch file contains the default subject and body. For example:
   [PATCH] docs: Test commit.

   Do not change this. Just add a comment about your changes before the “Signed-off-by” line.
   Don’t send your patch only to the maintainer! You also need to send it to a mailing list.


7. Check the reviews:
   You can keep track of the feedback on your patches at lkml.org (or in your email).

Tips

1. Be patient and don’t bother the maintainers, they are very busy people.


2. If you need to make changes to your patch, don’t send your new diff as a response to the first message. Instead, assign a version to the patch in the subject before sending the email. For example: [PATCH v2].


3. Keep a log of the changes made in each version:
   Signed-off-by: ...
---
Changes in v2:
- Remove unnecessary spaces.
Changes in v3:
- Improve text structure.


4. Send your diffs against the mainline.

Conclusion

I decided to write this post because I had some trouble submitting my first patch. It was a good experience and I hope this article helps other people experiencing issues.