This article is meant to help people to describe how to create, maintain and send patches that are easy to handle for the kernel maintainers.
Each patch should have a subject that concisely describes the patch which the email contains.
- It should not contain any filenames.
- Do not use the same subject for every patch in a patch series. Bear in mind that the subject of your email becomes a globally-unique identifier for that patch. It will propagate all the way into Linus' git tree. The subject may later be used in developer discussions which refer to the patch and people will want the ability to Google for the patch's subject.
- When sending a series of patches, the patches should be sequence numbered in the subject. Using git format-patch -X --cover-letter -o patches, where -X is the number of patches from HEAD or other commit identifier and -o specifies the output directory, will do all of this automatically. A cover letter file with subject of PATCH [0/X] where X is the total number of patches in the series, will be generated. You can then edit this file with a general top-level subject and give a detailed explanation of the patch series.
- It is nice if the subject includes mention of the subsystem which it affects like the following:
[PATCH 2/5] ext2: improve scalability of bitmap searching
- Various patch scripts used by developers will strip away any text inside brackets . You should place information which has no long-term relevance to the patch inside them. This includes the word
PATCHand any sequence numbering. The subsystem identifier
ext2should hence be outside brackets.
Bear in mind that the changelog will also propagate all the way to Linus' tree. The changelog must describe the patch fully.
- Here are some guidelines for changelog content:
- Why the kernel needed patching.
- What the overall design approach in the patch was.
- Implementation details.
- Any testing results.
- There is no point in mentioning what version of the kernel the patch applies to. This is not interesting information as once the patch is in git, it will probably be merged into a later kernel version than the one which you wrote it for anyway.
- Do not refer to earlier patches in the changelog of a new version of a patch. It is not very useful to have a git changelog which says "OK, this fixes the things you mentioned yesterday". Each iteration of the patch should contain a standalone changelog.
- Add a Signed-off-by: line with your name and email address. If you are the person responsible for submitting patches for your group or company, you may have multiple Signed-off-by lines.
All patches should be generated using the
git format-patch command. No exceptions.
Patches are submitted via email only. Please read Mailing-patches for instructions once you have completed formatting your patches with git.
- Avoid MIME and attachements if possible. Make sure that your email client does not wordwrap your patch. Make sure that your email client does not replace tabs with spaces. If you use a patch-corrupting mail clien tsuch as Firebird or Evolution, see the mailing patches for some hints.
- Mail yourself a decent-sized patch and check that it still applies.
This article is derived from Andrew Morton's article at http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt.