Finally you have your changes ready for the Linux Kernel and you want to share them with the community. For this you need to send them to the Linux Kernel Mailing List (LKML) and go through the review process. There are a lot of rules for sending your patches to this list and going through the process may be confusing for a newbie. This is a check list of things you have to do before sending you patches.
This is a long post so this is a short checklist to summarize it:
- subscribe to LKML and follow related discussions
- read Documentation/SubmittingPatches and apply what it says
- find and download the right git branch or tree for the subsystem you want to submit to
- rebase your patches to the latest version of the upstream branch
- fix your coding style using scripts/Lindent
- generate your patches with
git format-patch -n -s --cover-letter --subject-prefix="PATCH" and fill in a description in the cover letter file; mention the git tree you based your work on in the cover letter
- check for style errors with scripts/checkpatch.pl.
- send the patches to yourself using
git send-email and test if they apply cleanly on the upstream branch
- get a list of maintainers and main contributors using scripts/get_maintainer.pl
- sent the patches to LKML (linux-kernel@vger.kernel.org) and the maintainers using
git send-email
1. Subscribe to LKML
It is not necessary subscribe to the list for sending patches, but it is a good practice. You should subscribe to the list and check out the way things are done. You can learn a lot by watching the discussions going on the list. Beware that the list has a lot of traffic (200-300 emails daily), so you will probably not be able to read everything. You can create an email filter to select emails related to the area you want to submit to.
To see what mailing lists are available you can check vger.kernel.org/vger-lists.html. You can find LKML as the linux-kernel mailing list. You can subscribe by having an email conversation with the majordomo. You should also take a look at the other lists. If you find one for the subsystem you want to submit your patch to, you should also subscribe to that.
LKML is archived on various sites and one of them is lkml.org. You should first search for related discussions and patches in the archives; you can find somebody else has submitted a similar patch as yours or that there was already a discussion on this and the decision was different from your approach.
2. Read the kernel documentation on sending patches
The very first thing you need to do is to read the kernel documentation on submitting patches:
Documentation/SubmittingPatches also has a list of things you have to do before submitting your patch. I will not repeat the things mentioned there in this post, so you must read and follow what it says.
3. Get the right branch or git tree
The Linux Kernel is divided into several subsystems and areas of development. Each such area has its own maintainer and most often its own tree or branch. You need to find the tree or branch you need to rebase your patches to. Since the maintainer will be merging your patches, you need to rebase your patches on his branch so that there will be no conflicts.
You can find the maintainers and their trees in the MAINTAINERS file from the Linux Kernel Sources. Beware that some information on the git trees is deprecated. The best thing to do is to check LKML to see what branch other people are rebasing to. You can also check the list of kernel git trees from git.kernel.org.
If you cannot find anything relevant, you can rebase your change to the tip tree or linux-next.
4. Rebase your changes to the latest tip tree
Before submitting your change, make sure you have the latest changes from upstream. Update your git tree using git pull and rebase if necessary.
5. Is your patch whitespace-damaged?
The Linux Kernel has specific rules when it comes to coding style. This is the first thing reviewers will look at and the easiest thing to check and fix. These rules are described in the Linux Kernel Documentation in Documentation/CodingStyle. Even if you read and follow all that says there, you might miss some obvious things anyway. Hopefully, you have a helper tool in the Linux Kernel: Lindent.
Lindent is a script that uses the GNU indent to automatically fix your coding style. You can find it in your kernel sources in scripts/Lindent. When you run it you have to give the file you want indented as parameter. This is what Linus has to say about it in Documentation/CodingStyle:
Now, again, GNU indent has the same brain-dead settings that GNU emacs
has, which is why you need to give it a few command line options.
However, that's not too bad, because even the makers of GNU indent
recognize the authority of K&R (the GNU people aren't evil, they are
just severely misguided in this matter), so you just give indent the
options "-kr -i8" (stands for "K&R, 8 character indents"), or use
"scripts/Lindent", which indents in the latest style.
6. Generate the patches using git format-patch
The patches sent to LKML need to have a specific format which is described in Documentation/SubmittingPatches. Fortunately, git format-patch generates patches with this format so you can do this automatically.
There are several options for git-format which I use:
- -n will generate numbered patches in [PATCH n/m] format, even with a single patch.
- -s makes sure you do not forget the Signed-off-by: line.
- –cover-letter will generate a cover letter file so that you can fill in the description for your entire set of patches. If you only have one patch, you should skip this.
- –subject-prefix=”PATCH” can be use to change the default “[PATCH]” prefix to something else. This is useful when sending later versions to LKML and you need to use prefixes like “[PATCH v2]”.
This would be a standard git format patch command:
git format-patch -n -s --cover-letter --subject-prefix="PATCH" SHA-1
where SHA-1 is the change right before yours.
If you generated a cover letter, you will have a file 0000-cover-letter.patch. You need to edit it with a subject and description for your changes. It is a good practice to mention the git tree you based your work on in the cover letter.
7. Check coding style using checkpatch
Even if you followed all coding style rules you might still have missed something. Once you have generated your patch you can verify that there are no violation using checkpatch. You can find it in the Linux Kernel in scripts/checkpatch.pl and run it with the patch you generated before. If you find any issues, you should address them in the code, regenerate the patches and run checkpatchagain.
8. Send the patches to yourself using git send-email
Now that you have the patches ready, how do you send them to LKML?
As you may have read in Documentation/SubmittingPatches, there are some strict rules about not having HTML code in the emails you send to the list. Do not manually copy the content of the patch and paste it in your email! Even if you set your email client to use plain text email, this is not enough. The best way is to use git send-email.
The first step is to send the patches to yourself and see if they apply properly. The easiest way to work with git send-email is to create different identities that you can use. I am using my GMail account with git send-email, so this is how my configuration looks like in ~/.gitconfig:
[sendemail "me"]
smtpserver = smtp.gmail.com
smtpuser = myuser@gmail.com
smtpencryption = tls
smtpserverport = 587
to = My Name
chainreplyto = false
suppresscc = all
It is a good practice to send all your patches in the same email thread as replies to the cover letter. For this, you need to set chainreplyto = false.
By default, git send-email will send an email to all people who signed-off on the patch. When you are just sending the patches to yourself for testing you do not want that, so you should add supresscc = all in the config.
Send the patches using the above configuration with:
git send-email --identity=me *.patch
Once you received the patches by email you need to check if they apply cleanly. You need to be able to export the emails to your machine. The GMail interface does not offer this feature, so you have to use an email client for this. I use Thunderbird and I can easily export and save the emails. Check out the upstream branch you were working on and apply the saved emails using git am. git am knows to apply entire emails so you do not need to do any changes to the saved messages. If they apply cleanly then you are ready to send your patches upstream. If not, go back and see what you did wrong.
9. Find out who the maintainers are
You are ready to send your patches upstream. But whom do you send them to?
You need to include the LKML (linux-kernel@vger.kernel.org), but you also need to add the maintainers. The maintainers for each subsystem are described in MAINTAINERS, but you can also use the get_maintainer script. You can find this script in the Linux Kernel sources in scripts/get_maintainer.pl. You need to run from the Linux Kernel tree on you patches:
scripts/get_maintainer.pl *.patch
This will give you the list of maintainers and main contributors that you should consider adding to your patch.
10. Send your patches to LKML and the maintainers
For sending the patches to LKML you need do use git send-email and set up a similar configuration as described in step 8. If you do this on a regular basis, you can add the maintainers to .gitconfig. Otherwise, you can just specify them in the git send-email command with --to and --cc.
This is an example for the git send-email configuration from ~/.gitconfig :
[sendemail "lkml"]
smtpserver = smtp.gmail.com
smtpuser = myuser@gmail.com
smtpencryption = tls
smtpserverport = 587
chainreplyto = false
cc = LKML <linux-kernel@vger.kernel.org>
to = mantainer_1
Then you can actually send the patches using:
git send-email --identity=lkml *.patch
You should verify that all your patches made it to the list. You can check the last 100 messages from the archives. You may need to wait a while, since this is an archive and it will take a little time for your patches to appear. It may take around 10-15 min for your first patch to appear in the archive. If you have more patches you should wait longer.
That’s it! Now you have your first patch on LKML!
Yet another * programming blog 