15: POSTING PATCHES 2 3Sooner or later, the time comes when your work is ready to be presented to 4the community for review and, eventually, inclusion into the mainline 5kernel. Unsurprisingly, the kernel development community has evolved a set 6of conventions and procedures which are used in the posting of patches; 7following them will make life much easier for everybody involved. This 8document will attempt to cover these expectations in reasonable detail; 9more information can also be found in the files SubmittingPatches, 10SubmittingDrivers, and SubmitChecklist in the kernel documentation 11directory. 12 13 145.1: WHEN TO POST 15 16There is a constant temptation to avoid posting patches before they are 17completely "ready." For simple patches, that is not a problem. If the 18work being done is complex, though, there is a lot to be gained by getting 19feedback from the community before the work is complete. So you should 20consider posting in-progress work, or even making a git tree available so 21that interested developers can catch up with your work at any time. 22 23When posting code which is not yet considered ready for inclusion, it is a 24good idea to say so in the posting itself. Also mention any major work 25which remains to be done and any known problems. Fewer people will look at 26patches which are known to be half-baked, but those who do will come in 27with the idea that they can help you drive the work in the right direction. 28 29 305.2: BEFORE CREATING PATCHES 31 32There are a number of things which should be done before you consider 33sending patches to the development community. These include: 34 35 - Test the code to the extent that you can. Make use of the kernel's 36 debugging tools, ensure that the kernel will build with all reasonable 37 combinations of configuration options, use cross-compilers to build for 38 different architectures, etc. 39 40 - Make sure your code is compliant with the kernel coding style 41 guidelines. 42 43 - Does your change have performance implications? If so, you should run 44 benchmarks showing what the impact (or benefit) of your change is; a 45 summary of the results should be included with the patch. 46 47 - Be sure that you have the right to post the code. If this work was done 48 for an employer, the employer likely has a right to the work and must be 49 agreeable with its release under the GPL. 50 51As a general rule, putting in some extra thought before posting code almost 52always pays back the effort in short order. 53 54 555.3: PATCH PREPARATION 56 57The preparation of patches for posting can be a surprising amount of work, 58but, once again, attempting to save time here is not generally advisable 59even in the short term. 60 61Patches must be prepared against a specific version of the kernel. As a 62general rule, a patch should be based on the current mainline as found in 63Linus's git tree. It may become necessary to make versions against -mm, 64linux-next, or a subsystem tree, though, to facilitate wider testing and 65review. Depending on the area of your patch and what is going on 66elsewhere, basing a patch against these other trees can require a 67significant amount of work resolving conflicts and dealing with API 68changes. 69 70Only the most simple changes should be formatted as a single patch; 71everything else should be made as a logical series of changes. Splitting 72up patches is a bit of an art; some developers spend a long time figuring 73out how to do it in the way that the community expects. There are a few 74rules of thumb, however, which can help considerably: 75 76 - The patch series you post will almost certainly not be the series of 77 changes found in your working revision control system. Instead, the 78 changes you have made need to be considered in their final form, then 79 split apart in ways which make sense. The developers are interested in 80 discrete, self-contained changes, not the path you took to get to those 81 changes. 82 83 - Each logically independent change should be formatted as a separate 84 patch. These changes can be small ("add a field to this structure") or 85 large (adding a significant new driver, for example), but they should be 86 conceptually small and amenable to a one-line description. Each patch 87 should make a specific change which can be reviewed on its own and 88 verified to do what it says it does. 89 90 - As a way of restating the guideline above: do not mix different types of 91 changes in the same patch. If a single patch fixes a critical security 92 bug, rearranges a few structures, and reformats the code, there is a 93 good chance that it will be passed over and the important fix will be 94 lost. 95 96 - Each patch should yield a kernel which builds and runs properly; if your 97 patch series is interrupted in the middle, the result should still be a 98 working kernel. Partial application of a patch series is a common 99 scenario when the "git bisect" tool is used to find regressions; if the 100 result is a broken kernel, you will make life harder for developers and 101 users who are engaging in the noble work of tracking down problems. 102 103 - Do not overdo it, though. One developer recently posted a set of edits 104 to a single file as 500 separate patches - an act which did not make him 105 the most popular person on the kernel mailing list. A single patch can 106 be reasonably large as long as it still contains a single *logical* 107 change. 108 109 - It can be tempting to add a whole new infrastructure with a series of 110 patches, but to leave that infrastructure unused until the final patch 111 in the series enables the whole thing. This temptation should be 112 avoided if possible; if that series adds regressions, bisection will 113 finger the last patch as the one which caused the problem, even though 114 the real bug is elsewhere. Whenever possible, a patch which adds new 115 code should make that code active immediately. 116 117Working to create the perfect patch series can be a frustrating process 118which takes quite a bit of time and thought after the "real work" has been 119done. When done properly, though, it is time well spent. 120 121 1225.4: PATCH FORMATTING 123 124So now you have a perfect series of patches for posting, but the work is 125not done quite yet. Each patch needs to be formatted into a message which 126quickly and clearly communicates its purpose to the rest of the world. To 127that end, each patch will be composed of the following: 128 129 - An optional "From" line naming the author of the patch. This line is 130 only necessary if you are passing on somebody else's patch via email, 131 but it never hurts to add it when in doubt. 132 133 - A one-line description of what the patch does. This message should be 134 enough for a reader who sees it with no other context to figure out the 135 scope of the patch; it is the line that will show up in the "short form" 136 changelogs. This message is usually formatted with the relevant 137 subsystem name first, followed by the purpose of the patch. For 138 example: 139 140 gpio: fix build on CONFIG_GPIO_SYSFS=n 141 142 - A blank line followed by a detailed description of the contents of the 143 patch. This description can be as long as is required; it should say 144 what the patch does and why it should be applied to the kernel. 145 146 - One or more tag lines, with, at a minimum, one Signed-off-by: line from 147 the author of the patch. Tags will be described in more detail below. 148 149The above three items should, normally, be the text used when committing 150the change to a revision control system. They are followed by: 151 152 - The patch itself, in the unified ("-u") patch format. Using the "-p" 153 option to diff will associate function names with changes, making the 154 resulting patch easier for others to read. 155 156You should avoid including changes to irrelevant files (those generated by 157the build process, for example, or editor backup files) in the patch. The 158file "dontdiff" in the Documentation directory can help in this regard; 159pass it to diff with the "-X" option. 160 161The tags mentioned above are used to describe how various developers have 162been associated with the development of this patch. They are described in 163detail in the SubmittingPatches document; what follows here is a brief 164summary. Each of these lines has the format: 165 166 tag: Full Name <email address> optional-other-stuff 167 168The tags in common use are: 169 170 - Signed-off-by: this is a developer's certification that he or she has 171 the right to submit the patch for inclusion into the kernel. It is an 172 agreement to the Developer's Certificate of Origin, the full text of 173 which can be found in Documentation/SubmittingPatches. Code without a 174 proper signoff cannot be merged into the mainline. 175 176 - Acked-by: indicates an agreement by another developer (often a 177 maintainer of the relevant code) that the patch is appropriate for 178 inclusion into the kernel. 179 180 - Tested-by: states that the named person has tested the patch and found 181 it to work. 182 183 - Reviewed-by: the named developer has reviewed the patch for correctness; 184 see the reviewer's statement in Documentation/SubmittingPatches for more 185 detail. 186 187 - Reported-by: names a user who reported a problem which is fixed by this 188 patch; this tag is used to give credit to the (often underappreciated) 189 people who test our code and let us know when things do not work 190 correctly. 191 192 - Cc: the named person received a copy of the patch and had the 193 opportunity to comment on it. 194 195Be careful in the addition of tags to your patches: only Cc: is appropriate 196for addition without the explicit permission of the person named. 197 198 1995.5: SENDING THE PATCH 200 201Before you mail your patches, there are a couple of other things you should 202take care of: 203 204 - Are you sure that your mailer will not corrupt the patches? Patches 205 which have had gratuitous white-space changes or line wrapping performed 206 by the mail client will not apply at the other end, and often will not 207 be examined in any detail. If there is any doubt at all, mail the patch 208 to yourself and convince yourself that it shows up intact. 209 210 Documentation/email-clients.txt has some helpful hints on making 211 specific mail clients work for sending patches. 212 213 - Are you sure your patch is free of silly mistakes? You should always 214 run patches through scripts/checkpatch.pl and address the complaints it 215 comes up with. Please bear in mind that checkpatch.pl, while being the 216 embodiment of a fair amount of thought about what kernel patches should 217 look like, is not smarter than you. If fixing a checkpatch.pl complaint 218 would make the code worse, don't do it. 219 220Patches should always be sent as plain text. Please do not send them as 221attachments; that makes it much harder for reviewers to quote sections of 222the patch in their replies. Instead, just put the patch directly into your 223message. 224 225When mailing patches, it is important to send copies to anybody who might 226be interested in it. Unlike some other projects, the kernel encourages 227people to err on the side of sending too many copies; don't assume that the 228relevant people will see your posting on the mailing lists. In particular, 229copies should go to: 230 231 - The maintainer(s) of the affected subsystem(s). As described earlier, 232 the MAINTAINERS file is the first place to look for these people. 233 234 - Other developers who have been working in the same area - especially 235 those who might be working there now. Using git to see who else has 236 modified the files you are working on can be helpful. 237 238 - If you are responding to a bug report or a feature request, copy the 239 original poster as well. 240 241 - Send a copy to the relevant mailing list, or, if nothing else applies, 242 the linux-kernel list. 243 244 - If you are fixing a bug, think about whether the fix should go into the 245 next stable update. If so, stable@kernel.org should get a copy of the 246 patch. Also add a "Cc: stable@kernel.org" to the tags within the patch 247 itself; that will cause the stable team to get a notification when your 248 fix goes into the mainline. 249 250When selecting recipients for a patch, it is good to have an idea of who 251you think will eventually accept the patch and get it merged. While it 252is possible to send patches directly to Linus Torvalds and have him merge 253them, things are not normally done that way. Linus is busy, and there are 254subsystem maintainers who watch over specific parts of the kernel. Usually 255you will be wanting that maintainer to merge your patches. If there is no 256obvious maintainer, Andrew Morton is often the patch target of last resort. 257 258Patches need good subject lines. The canonical format for a patch line is 259something like: 260 261 [PATCH nn/mm] subsys: one-line description of the patch 262 263where "nn" is the ordinal number of the patch, "mm" is the total number of 264patches in the series, and "subsys" is the name of the affected subsystem. 265Clearly, nn/mm can be omitted for a single, standalone patch. 266 267If you have a significant series of patches, it is customary to send an 268introductory description as part zero. This convention is not universally 269followed though; if you use it, remember that information in the 270introduction does not make it into the kernel changelogs. So please ensure 271that the patches, themselves, have complete changelog information. 272 273In general, the second and following parts of a multi-part patch should be 274sent as a reply to the first part so that they all thread together at the 275receiving end. Tools like git and quilt have commands to mail out a set of 276patches with the proper threading. If you have a long series, though, and 277are using git, please provide the --no-chain-reply-to option to avoid 278creating exceptionally deep nesting. 279