Submitting patches: the essential guide to getting your code into the kernel — The Linux Kernel documentation

Working with the development community
Internal API manuals
Development tools and processes
User-oriented documentation
Firmware-related documentation
Architecture-specific documentation
For a person or company who wishes to submit a change to the Linux kernel, the process can sometimes be daunting if you’re not familiar with “the system.” This text is a collection of suggestions which can greatly increase the chances of your change being accepted.
This document contains a large number of suggestions in a relatively terse format. For detailed information on how the kernel development process works, see A guide to the Kernel Development Process. Also, read Linux Kernel patch submission checklist for a list of items to check before submitting code. For device tree binding patches, read Submitting Devicetree (DT) binding patches.
This documentation assumes that you’re using git to prepare your patches. If you’re unfamiliar with git, you would be well-advised to learn how to use it, it will make your life as a kernel developer and in general much easier.
Some subsystems and maintainer trees have additional information about their workflow and expectations, see Subsystem and maintainer tree specific development process notes.
If you do not have a repository with the current kernel source handy, use git to obtain one. You’ll want to start with the mainline repository, which can be grabbed with:
Note, however, that you may not want to develop against the mainline tree directly. Most subsystem maintainers run their own trees and want to see patches prepared against those trees. See the T: entry for the subsystem in the MAINTAINERS file to find that tree, or simply ask the maintainer if the tree is not listed there.
Describe your problem. Whether your patch is a one-line bug fix or 5000 lines of a new feature, there must be an underlying problem that motivated you to do this work. Convince the reviewer that there is a problem worth fixing and that it makes sense for them to read past the first paragraph.
Describe user-visible impact. Straight up crashes and lockups are pretty convincing, but not all bugs are that blatant. Even if the problem was spotted during code review, describe the impact you think it can have on users. Keep in mind that the majority of Linux installations run kernels from secondary stable trees or vendor/product-specific trees that cherry-pick only specific patches from upstream, so include anything that could help route your change downstream: provoking circumstances, excerpts from dmesg, crash descriptions, performance regressions, latency spikes, lockups, etc.
Quantify optimizations and trade-offs. If you claim improvements in performance, memory consumption, stack footprint, or binary size, include numbers that back them up. But also describe non-obvious costs. Optimizations usually aren’t free but trade-offs between CPU, memory, and readability; or, when it comes to heuristics, between different workloads. Describe the expected downsides of your optimization so that the reviewer can weigh costs against benefits.
Once the problem is established, describe what you are actually doing about it in technical detail. It’s important to describe the change in plain English for the reviewer to verify that the code is behaving as you intend it to.
The maintainer will thank you if you write your patch description in a form which can be easily pulled into Linux’s source code management system, git, as a “commit log”. See The canonical patch format.
Solve only one problem per patch. If your description starts to get long, that’s a sign that you probably need to split up your patch. See Separate your changes.
When you submit or resubmit a patch or patch series, include the complete patch description and justification for it. Don’t just say that this is version N of the patch (series). Don’t expect the subsystem maintainer to refer back to earlier patch versions or referenced URLs to find the patch description and put that into the patch. I.e., the patch (series) and its description should be self-contained. This benefits both the maintainers and reviewers. Some reviewers probably didn’t even receive earlier versions of the patch.
Describe your changes in imperative mood, e.g. “make xyzzy do frotz” instead of “[This patch] makes xyzzy do frotz” or “[I] changed xyzzy to do frotz”, as if you are giving orders to the codebase to change its behaviour.
If you want to refer to a specific commit, don’t just refer to the SHA-1 ID of the commit. Please also include the oneline summary of the commit, to make it easier for reviewers to know what it is about. Example:
You should also be sure to use at least the first twelve characters of the SHA-1 ID. The kernel repository holds a lot of objects, making collisions with shorter IDs a real possibility. Bear in mind that, even if there is no collision with your six-character ID now, that condition may change five years from now.
If related discussions or any other background information behind the change can be found on the web, add ‘Link:’ tags pointing to it. If the patch is a result of some earlier mailing list discussions or something documented on the web, point to it.
When linking to mailing list archives, preferably use the lore.kernel.org message archiver service. To create the link URL, use the contents of the Message-ID header of the message without the surrounding angle brackets. For example:
Please check the link to make sure that it is actually working and points to the relevant message.
However, try to make your explanation understandable without external resources. In addition to giving a URL to a mailing list archive or bug, summarize the relevant points of the discussion that led to the patch as submitted.
In case your patch fixes a bug, use the ‘Closes:’ tag with a URL referencing the report in the mailing list archives or a public bug tracker. For example:
Some bug trackers have the ability to close issues automatically when a comm