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