Getting Started |
Contents |
Patches
What constitutes a good patch? What kind of attributes do Ubuntu developers follow before they send a patch upstream? This document is an effort to document "best practices" that people follow to prepare patches. The target audience for this document would be someone who is capable of fixing something and making a patch, but might not know the ins and outs of a software project enough to know how to best send someone a patch.
Attributes
Things to consider with upstreams before sending a patch.
- Willingness to rework/reimplement parts upstream doesn't like - Expect to have some form of review by someone in the upstream project to review you work, you should be willing to adapt your patch to meet their requirements.
- General applicability instead of being distribution specific - Remember that distributions are downstream from most projects, your patch should be generic and not distribution specific. Don't make assumptions about plumbing, if you're unsure, ask someone.
- Correctness - If upstream is going to integrate your patch and maintain that piece of code going forward it should be clean and correct.
- Following code style/indentation standards - When in doubt, make the code you submit look like the rest of the code in the project.
- Version of your software (trunk vs. what is released) - be clear as to which version of the project the patch applies to. It doesn't hurt to check the trunk of the project to see if it applies there as well. Some upstreams are very "trunk" oriented, so it makes sense for you to provide a patch that applies to trunk.
- Speed at which it's provided
- Documentation in the patch - what the patch does, etc. References to bug descriptions/discussion and bug trackers would be useful.
Please also check out our patch tagging guidelines. It's important to document internally where we got the patch from and why it is important.
- An accompanying unit test - If the upstream project has unit tests, test the patch with that test.
- If patch is invasive/extensive, asking you beforehand to see if you are interested in integrating these kind of changes.
- One bug/feature per patch - Most projects prefer this instead of one huge invasive diff.
General Tips
- Know your audience. Everyone has style and pet peeves about how code should be formatted. Realize that they're all silly including yours. The compiler doesn't care about formatting. Look through the code and make sure that your patch is entirely compatible with the formatting of the rest of the code. Check tabs vs. spaces. Are variables always declared at the beginning of functions? Where are prototypes of new functions put? Are variables initialized in a particular way?
- Make it obvious. After you make a patch, actually read the patch. Is it obvious what it's doing? Is something getting included that shouldn't be? Should you adjust the number of surrounding lines in the patch to make it more understandable. Like all things, you have just a few seconds to make an impression, make it seem like reading through this patch is going to be easy instead of something that the maintainer will have to think about.
- Ensure that it applies cleanly. If you've made it against a stable version ensure that it applies cleanly to development versions so that it can be applied quickly and easily.
- Justify it. There is a reason that this patch is important and make sure to convey it. The reason isn't "removing init line" it is "in function X this function is called which causes this problem." No, linking to the bug report is not a replacement. There are tons of comments that are debugging the problem. Provide an executive summary.
- Break it up. Sometimes a fix to a problem contains several smaller fixes to different sub problems. It is much better to break these into smaller bite-size patches. They're easier to understand and more likely to get applied.
- Be Collaborative. You are asking someone to take time out of their day and look at your work. Sure, they want their software to be better but they don't have to listen to you. Similarly you are contributing to their project so having a positive attitude with working someone helps here.
- Read this list again. Notice that everything on this list is more related to social interactions than code interactions. Open Source software is about people. Don't forget it.
Other Resources
Patches to Packages - a guide to patching Ubuntu
Fixing bugs in Ubuntu - a step-by-step guide for fixing a bug in an ordinary ubuntu package (tutorial)
- Kernel:
Kernel Bug Fixing - a step-by-step guide for fixing a kernel bug with an example.
Kernel Patches - Some kernel-specific tips for dealing with patches.