Add link to successful example of getting patches merged upstream and into Ubuntu
|Deletions are marked like this.||Additions are marked like this.|
|Line 80:||Line 80:|
|=== Additional Examples ===
The Ubuntu kernel team's target scenario is to have little to no divergence from the upstream linux kernel. As such, the Ubuntu kernel team's preferred policy is for all patches to be submitted and accepted into the upstream kernel before agreeing to pull them into the Ubuntu kernel. The following will help describe the process of how to go about getting a patch included into the Ubuntu kernel.
Typical Patch Life Cycle
This outlines the typical steps a patch should go through before it's included into the Ubuntu kernel.
- Patch is created and thoroughly tested.
File a bug in Launchpad documenting the issue and what the patch does to resolve that issue.
- Attach the patch to the Launchpad bug. Be sure to tick the "This attachment is a patch" checkbox when attaching.
Optional: if you want your patch reviewed before submitting upstream, please send it in an email to the Ubuntu kernel team mailing list <firstname.lastname@example.org>.
These types of patches can be submitted on the Ubuntu kernel team mailing list <email@example.com> in one of two forms:
- A pull request from a publicly available git repository, e.g., attach the output of 'git request-pull'. This is the preferred method for large or numerous patches.
From your local git repository run the command 'git format-patch -1 <SHA1>' and email the resulting file. Beware of tab mangling and line wrapping. A good rule of thumb is to email the patch to yourself first and verify it applies cleanly.
- Don't forget to add your "Signed-off-by:" line.
- The patch should be reviewed by the Ubuntu kernel team and feedback will likely be given. Be sure to make any suggested improvements and resubmit for another review if necessary.
Once the patch is ready, submit it upstream. See the the Submitting a Patch Upstream section below.
- The patch will typically undergo a review by the upstream kernel developers and may receive additional comments on how to improve the patch. Be sure to make the suggested improvements and resubmit until it's finally accepted.
- At this point, it's also a good idea to add a reference in the Launchpad bug to the thread of the patch posted upstream.
- Patch accepted upstream.
- Once upstream, the patch will automatically land in the Ubuntu kernel.
If this patch should be cherry-picked immediately into the Ubuntu kernel from upstream, please refer to the Submitting a Patch to the Ubuntu Kernel
If you need assistance with any of these steps, please refer to the help section below.
Submitting a Patch Upstream
If a patch will benefit the entire kernel community as a whole it should go upstream first. Once the patch is integrated upstream, the patch will automatically trickle down into the Ubuntu kernel. If a patch has not been submitted upstream it's not likely to be applied to the Ubuntu kernel. So how does one go about submitting a patch to the upstream kernel?
First, read the upstream patch submission documentation. Do not just skim or browse this. It's rude to waste an upstream developers time by not knowing how to properly submit a patch, especially when the patch submission process has been fully documented. The upstream developers take patches and contributions seriously, so please return the favor by submitting a patch properly.
Look at the MAINTAINERS file to know where to send the patch.
- Be sure to create the patch against the upstream kernel source, not the Ubuntu kernel source.
Some subsystems maintain their own git trees which are then merged with Linus'. If this is the case, create the patch against the subsystem's tree. Otherwise use http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git.
git clone http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git
- Make sure to maintain full provenance of the patch by signing off on it (ie add your Signed-off-by:)
Example of Submitting a Patch Upstream
Bug 323592 - reboot freeze of Dell XPS 710
This particular bug was fixed by creating a patch to add a reboot quirk for this particular system. This patch would be beneficial not only for Ubuntu users but all users who had this hardware. As such, this patch was submitted upstream as follows:
- The patch was first thoroughly tested and confirmed to fix the issue.
The submitter carefully read the upstream patch submission documentation and noted some key elements to keep in mind:
- the patch needed to have a well written description
- the patch followed the upstream kernel coding style
- the patch would be submitted as inline text in an email (ie. no attachments, no links, etc.)
- patch was generated against the latest kernel available
- "[PATCH]" was included in the subject of the email
- patch was signed off
The submitter examined the MAINTAINERS file to see who and where to submit the patch to:
X86 ARCHITECTURE (32-BIT AND 64-BIT) P: Thomas Gleixner M: firstname.lastname@example.org P: Ingo Molnar M: email@example.com P: H. Peter Anvin M: firstname.lastname@example.org M: email@example.com T: git git://git.kernel.org/pub/scm/linux/kernel/git/x86/linux-2.6-x86.git S: Maintained F: Documentation/x86/ F: arch/x86/
After examining the MAINTAINERS file it was noted that this particular subsystem had it's own git tree. The patch was quickly rebased against the linux-2.6-x86.git tree.
- The email was then crafted and was sent to the maintainers (Thomas Gleixner, Ingo Molnar, H. Peter Anvin), the x86 kernel mailing list, and LKML.
- The patch was accepted and merged upstream
When this patch was submitted it also had a "Cc: <firstname.lastname@example.org>" line included in the email. That was to make sure it was also submitted to the stable updates tree once it was accepted. Most patches won't likely need this line in the email.
Submitting a Patch to the Ubuntu Kernel
The majority of patches should go upstream first before the Ubuntu kernel team will consider applying them to the Ubuntu kernel. Refer to the Submitting a Patch Upstream section above. Once a patch has been submitted and accepted upstream it will automatically find it's way into the Ubuntu kernel. If the upstream patch is something that should be cherry-picked as soon as possible into the Ubuntu kernel tree, please do the following:
File a bug in Launchpad and be sure to reference the upstream SHA1 git id that the Ubuntu kernel team should cherry-pick.
Send an email to the Ubuntu kernel team mailing list <email@example.com> requesting the cherry-pick. Also be sure to reference the Launchpad bug in your email.
There are exceptions that are sometimes made. If a patch is for example a Critical bug fix, the Ubuntu kernel team may opt to temporarily carry the patch while it's going through the upstream submission process. Patches must still adhere to the following:
- A bug should also be filed in Launchpad for tracking purposes.
- The patch should have full provenance (including your Signed-off-by:), i.e., who wrote the patch, where it came from, and a descriptive commit log message.
From your local git repository run the command 'git format-patch -1 <SHA1>' and email the resulting file. Beware of tab mangling. Use an email attachment if necessary.
The email to the Ubuntu kernel team mailing list <firstname.lastname@example.org> should reference the upstream thread where discussion is taking place regarding the patch as well as the Launchpad bug #.
Finally, there do exist scenarios where a patch is Ubuntu specific. For example, Bug 393517. If this is the case, file a bug in Launchpad. Then send an email to the Ubuntu kernel team mailing list <email@example.com>.
Reasons Why the Ubuntu Kernel Team Won't Take a Patch
- "If it ain't good enough for Linus it ain't good enough for us." That's not 100% true, but the basic idea is that if the patch is not in upstream, that generally means they aren't stable. Ubuntu's kernel is not a testing ground for developing features.
- Maintaining a patch in our tree is not easy. Let's say we include v0.54 of some patch. Later, we want to sync up to the latest version of this patch. It's not easy to simply revert v0.54, because merges could have changed some of the code. Not to mention, there are very few patches like this that provide incremental changes between versions.
- Patching stock code means we can't get upstream kernel maintainers to help us much anymore. If our users experience bugs, we'll have to get them to try a stock kernel before being able to push the bug to upstream.
- Patching stock code means we have to worry about merges between the patch and code it touches. This can happen while we are following upstream development of the kernel, or when doing security patches for released kernels.
- Patching stock code opens up to unforeseen security issues. The patch you are asking to include could contain potential security problems, which we would likely never hear about, since the code isn't part of the stock kernel.
- Patching stock code could introduce bugs that even users who aren't getting the features of the patch would see (Xen is a good example of this). Adding bugs is bad.
- The patch is not against a new enough kernel. For example, at the time of writing this, Xen was still only stable against 2.6.16, but the kernel we are working on is 2.6.20-pre. The 2.6.20 kernel line broke even our third-party drivers.
- Confusion. This applies to patches that people want compiled as a separate kernel flavour. While we've done this for other features, it is not always good to have so many types of kernels available. Not to mention we'll also have people wanting flavour foo compiled with flavour bar, to provide a foo-bar kernel. We don't want to make a habit of this.
- A very uncommon reason, but just as important, is that the patch is just crap or serves no real purpose. Don't be offended.
- And the most important reason is, we just don't have time. Think if we included everyone's pet patch, and had to maintain them all. We'd be so swamped, we couldn't keep Ubuntu the great stable Linux OS it is now.
The Patch Wasn't Accepted, Now What?
There's usually a good reason why a patch wasn't accepted and it's usually explained in a reply. If there are suggestions for improvements that need to be done to the patch before it'll be accepted, make those improvements and re-submit. Most patches go through this type of review process and will need to be modified and re-submitted a few times before they are accepted. Don't give up.
There are some patches that don't make it upstream or into the Ubuntu kernel. Some people seem to be able, and God help them, willing to maintain a kernel package outside of Ubuntu's main repository. This is great if someone is willing to do this but it's not recommended. If someone opts for this route, things usually happen in stages. Most custom kernels never make it past the first stage.
- People create custom kernels built against the Ubuntu source and provide it publicly somewhere. They take on all the responsibility of keeping it current.
- If the package is used enough, sometimes it can make it into Universe, and made available to a wider audience. The patch would build depend on the Ubuntu kernel source, and easily stay in sync with updates to it. It would also be built on all available architectures. For this to happen, takes a greater degree of commitment from the person maintaining this package.
- Hopefully, some time after this stage the patch will be reconsidered for inclusion in upstream kernel. If not, then there's probably very little chance it would be included in the main Ubuntu kernel, but things can happen.
Colin: 1 & 2 would be much easier if building linux-restricted-modules against non-standard flavours were supported. I submitted some changes in a bug report but I don't think it has been looked at; wouldn't something similar go a long way towards facilitating kernel customization? --MattPrice
If you need assistance or have any questions regarding a patch, need a patch to be reviewed, or need help getting the patch submitted upstream, the Ubuntu kernel team would be happy to help. Please contact them either through the Ubuntu kernel team mailing list <firstname.lastname@example.org> or join the #ubuntu-kernel channel on the FreeNode IRC server.