Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 1 | |
| 2 | How to Get Your Change Into the Linux Kernel |
| 3 | or |
| 4 | Care And Operation Of Your Linus Torvalds |
| 5 | |
| 6 | |
| 7 | |
| 8 | For a person or company who wishes to submit a change to the Linux |
| 9 | kernel, the process can sometimes be daunting if you're not familiar |
| 10 | with "the system." This text is a collection of suggestions which |
| 11 | can greatly increase the chances of your change being accepted. |
| 12 | |
| 13 | If you are submitting a driver, also read Documentation/SubmittingDrivers. |
| 14 | |
| 15 | |
| 16 | |
| 17 | -------------------------------------------- |
| 18 | SECTION 1 - CREATING AND SENDING YOUR CHANGE |
| 19 | -------------------------------------------- |
| 20 | |
| 21 | |
| 22 | |
| 23 | 1) "diff -up" |
| 24 | ------------ |
| 25 | |
| 26 | Use "diff -up" or "diff -uprN" to create patches. |
| 27 | |
| 28 | All changes to the Linux kernel occur in the form of patches, as |
| 29 | generated by diff(1). When creating your patch, make sure to create it |
| 30 | in "unified diff" format, as supplied by the '-u' argument to diff(1). |
| 31 | Also, please use the '-p' argument which shows which C function each |
| 32 | change is in - that makes the resultant diff a lot easier to read. |
| 33 | Patches should be based in the root kernel source directory, |
| 34 | not in any lower subdirectory. |
| 35 | |
| 36 | To create a patch for a single file, it is often sufficient to do: |
| 37 | |
| 38 | SRCTREE= linux-2.4 |
| 39 | MYFILE= drivers/net/mydriver.c |
| 40 | |
| 41 | cd $SRCTREE |
| 42 | cp $MYFILE $MYFILE.orig |
| 43 | vi $MYFILE # make your change |
| 44 | cd .. |
| 45 | diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch |
| 46 | |
| 47 | To create a patch for multiple files, you should unpack a "vanilla", |
| 48 | or unmodified kernel source tree, and generate a diff against your |
| 49 | own source tree. For example: |
| 50 | |
| 51 | MYSRC= /devel/linux-2.4 |
| 52 | |
| 53 | tar xvfz linux-2.4.0-test11.tar.gz |
| 54 | mv linux linux-vanilla |
| 55 | wget http://www.moses.uklinux.net/patches/dontdiff |
| 56 | diff -uprN -X dontdiff linux-vanilla $MYSRC > /tmp/patch |
| 57 | rm -f dontdiff |
| 58 | |
| 59 | "dontdiff" is a list of files which are generated by the kernel during |
| 60 | the build process, and should be ignored in any diff(1)-generated |
| 61 | patch. dontdiff is maintained by Tigran Aivazian <tigran@veritas.com> |
| 62 | |
| 63 | Make sure your patch does not include any extra files which do not |
| 64 | belong in a patch submission. Make sure to review your patch -after- |
| 65 | generated it with diff(1), to ensure accuracy. |
| 66 | |
| 67 | If your changes produce a lot of deltas, you may want to look into |
| 68 | splitting them into individual patches which modify things in |
| 69 | logical stages, this will facilitate easier reviewing by other |
| 70 | kernel developers, very important if you want your patch accepted. |
| 71 | There are a number of scripts which can aid in this; |
| 72 | |
| 73 | Quilt: |
| 74 | http://savannah.nongnu.org/projects/quilt |
| 75 | |
| 76 | Randy Dunlap's patch scripts: |
| 77 | http://developer.osdl.org/rddunlap/scripts/patching-scripts.tgz |
| 78 | |
| 79 | Andrew Morton's patch scripts: |
| 80 | http://www.zip.com.au/~akpm/linux/patches/patch-scripts-0.16 |
| 81 | |
| 82 | 2) Describe your changes. |
| 83 | |
| 84 | Describe the technical detail of the change(s) your patch includes. |
| 85 | |
| 86 | Be as specific as possible. The WORST descriptions possible include |
| 87 | things like "update driver X", "bug fix for driver X", or "this patch |
| 88 | includes updates for subsystem X. Please apply." |
| 89 | |
| 90 | If your description starts to get long, that's a sign that you probably |
| 91 | need to split up your patch. See #3, next. |
| 92 | |
| 93 | |
| 94 | |
| 95 | 3) Separate your changes. |
| 96 | |
| 97 | Separate each logical change into its own patch. |
| 98 | |
| 99 | For example, if your changes include both bug fixes and performance |
| 100 | enhancements for a single driver, separate those changes into two |
| 101 | or more patches. If your changes include an API update, and a new |
| 102 | driver which uses that new API, separate those into two patches. |
| 103 | |
| 104 | On the other hand, if you make a single change to numerous files, |
| 105 | group those changes into a single patch. Thus a single logical change |
| 106 | is contained within a single patch. |
| 107 | |
| 108 | If one patch depends on another patch in order for a change to be |
| 109 | complete, that is OK. Simply note "this patch depends on patch X" |
| 110 | in your patch description. |
| 111 | |
| 112 | |
| 113 | 4) Select e-mail destination. |
| 114 | |
| 115 | Look through the MAINTAINERS file and the source code, and determine |
| 116 | if your change applies to a specific subsystem of the kernel, with |
| 117 | an assigned maintainer. If so, e-mail that person. |
| 118 | |
| 119 | If no maintainer is listed, or the maintainer does not respond, send |
| 120 | your patch to the primary Linux kernel developer's mailing list, |
| 121 | linux-kernel@vger.kernel.org. Most kernel developers monitor this |
| 122 | e-mail list, and can comment on your changes. |
| 123 | |
| 124 | Linus Torvalds is the final arbiter of all changes accepted into the |
| 125 | Linux kernel. His e-mail address is <torvalds@osdl.org>. He gets |
| 126 | a lot of e-mail, so typically you should do your best to -avoid- sending |
| 127 | him e-mail. |
| 128 | |
| 129 | Patches which are bug fixes, are "obvious" changes, or similarly |
| 130 | require little discussion should be sent or CC'd to Linus. Patches |
| 131 | which require discussion or do not have a clear advantage should |
| 132 | usually be sent first to linux-kernel. Only after the patch is |
| 133 | discussed should the patch then be submitted to Linus. |
| 134 | |
| 135 | For small patches you may want to CC the Trivial Patch Monkey |
| 136 | trivial@rustcorp.com.au set up by Rusty Russell; which collects "trivial" |
| 137 | patches. Trivial patches must qualify for one of the following rules: |
| 138 | Spelling fixes in documentation |
| 139 | Spelling fixes which could break grep(1). |
| 140 | Warning fixes (cluttering with useless warnings is bad) |
| 141 | Compilation fixes (only if they are actually correct) |
| 142 | Runtime fixes (only if they actually fix things) |
| 143 | Removing use of deprecated functions/macros (eg. check_region). |
| 144 | Contact detail and documentation fixes |
| 145 | Non-portable code replaced by portable code (even in arch-specific, |
| 146 | since people copy, as long as it's trivial) |
| 147 | Any fix by the author/maintainer of the file. (ie. patch monkey |
| 148 | in re-transmission mode) |
| 149 | |
| 150 | |
| 151 | |
| 152 | 5) Select your CC (e-mail carbon copy) list. |
| 153 | |
| 154 | Unless you have a reason NOT to do so, CC linux-kernel@vger.kernel.org. |
| 155 | |
| 156 | Other kernel developers besides Linus need to be aware of your change, |
| 157 | so that they may comment on it and offer code review and suggestions. |
| 158 | linux-kernel is the primary Linux kernel developer mailing list. |
| 159 | Other mailing lists are available for specific subsystems, such as |
| 160 | USB, framebuffer devices, the VFS, the SCSI subsystem, etc. See the |
| 161 | MAINTAINERS file for a mailing list that relates specifically to |
| 162 | your change. |
| 163 | |
| 164 | Even if the maintainer did not respond in step #4, make sure to ALWAYS |
| 165 | copy the maintainer when you change their code. |
| 166 | |
| 167 | For small patches you may want to CC the Trivial Patch Monkey |
| 168 | trivial@rustcorp.com.au set up by Rusty Russell; which collects "trivial" |
| 169 | patches. Trivial patches must qualify for one of the following rules: |
| 170 | Spelling fixes in documentation |
| 171 | Spelling fixes which could break grep(1). |
| 172 | Warning fixes (cluttering with useless warnings is bad) |
| 173 | Compilation fixes (only if they are actually correct) |
| 174 | Runtime fixes (only if they actually fix things) |
| 175 | Removing use of deprecated functions/macros (eg. check_region). |
| 176 | Contact detail and documentation fixes |
| 177 | Non-portable code replaced by portable code (even in arch-specific, |
| 178 | since people copy, as long as it's trivial) |
| 179 | Any fix by the author/maintainer of the file. (ie. patch monkey |
| 180 | in re-transmission mode) |
| 181 | |
| 182 | |
| 183 | |
| 184 | 6) No MIME, no links, no compression, no attachments. Just plain text. |
| 185 | |
| 186 | Linus and other kernel developers need to be able to read and comment |
| 187 | on the changes you are submitting. It is important for a kernel |
| 188 | developer to be able to "quote" your changes, using standard e-mail |
| 189 | tools, so that they may comment on specific portions of your code. |
| 190 | |
| 191 | For this reason, all patches should be submitting e-mail "inline". |
| 192 | WARNING: Be wary of your editor's word-wrap corrupting your patch, |
| 193 | if you choose to cut-n-paste your patch. |
| 194 | |
| 195 | Do not attach the patch as a MIME attachment, compressed or not. |
| 196 | Many popular e-mail applications will not always transmit a MIME |
| 197 | attachment as plain text, making it impossible to comment on your |
| 198 | code. A MIME attachment also takes Linus a bit more time to process, |
| 199 | decreasing the likelihood of your MIME-attached change being accepted. |
| 200 | |
| 201 | Exception: If your mailer is mangling patches then someone may ask |
| 202 | you to re-send them using MIME. |
| 203 | |
| 204 | |
| 205 | |
| 206 | 7) E-mail size. |
| 207 | |
| 208 | When sending patches to Linus, always follow step #6. |
| 209 | |
| 210 | Large changes are not appropriate for mailing lists, and some |
| 211 | maintainers. If your patch, uncompressed, exceeds 40 kB in size, |
| 212 | it is preferred that you store your patch on an Internet-accessible |
| 213 | server, and provide instead a URL (link) pointing to your patch. |
| 214 | |
| 215 | |
| 216 | |
| 217 | 8) Name your kernel version. |
| 218 | |
| 219 | It is important to note, either in the subject line or in the patch |
| 220 | description, the kernel version to which this patch applies. |
| 221 | |
| 222 | If the patch does not apply cleanly to the latest kernel version, |
| 223 | Linus will not apply it. |
| 224 | |
| 225 | |
| 226 | |
| 227 | 9) Don't get discouraged. Re-submit. |
| 228 | |
| 229 | After you have submitted your change, be patient and wait. If Linus |
| 230 | likes your change and applies it, it will appear in the next version |
| 231 | of the kernel that he releases. |
| 232 | |
| 233 | However, if your change doesn't appear in the next version of the |
| 234 | kernel, there could be any number of reasons. It's YOUR job to |
| 235 | narrow down those reasons, correct what was wrong, and submit your |
| 236 | updated change. |
| 237 | |
| 238 | It is quite common for Linus to "drop" your patch without comment. |
| 239 | That's the nature of the system. If he drops your patch, it could be |
| 240 | due to |
| 241 | * Your patch did not apply cleanly to the latest kernel version |
| 242 | * Your patch was not sufficiently discussed on linux-kernel. |
| 243 | * A style issue (see section 2), |
| 244 | * An e-mail formatting issue (re-read this section) |
| 245 | * A technical problem with your change |
| 246 | * He gets tons of e-mail, and yours got lost in the shuffle |
| 247 | * You are being annoying (See Figure 1) |
| 248 | |
| 249 | When in doubt, solicit comments on linux-kernel mailing list. |
| 250 | |
| 251 | |
| 252 | |
| 253 | 10) Include PATCH in the subject |
| 254 | |
| 255 | Due to high e-mail traffic to Linus, and to linux-kernel, it is common |
| 256 | convention to prefix your subject line with [PATCH]. This lets Linus |
| 257 | and other kernel developers more easily distinguish patches from other |
| 258 | e-mail discussions. |
| 259 | |
| 260 | |
| 261 | |
| 262 | 11) Sign your work |
| 263 | |
| 264 | To improve tracking of who did what, especially with patches that can |
| 265 | percolate to their final resting place in the kernel through several |
| 266 | layers of maintainers, we've introduced a "sign-off" procedure on |
| 267 | patches that are being emailed around. |
| 268 | |
| 269 | The sign-off is a simple line at the end of the explanation for the |
| 270 | patch, which certifies that you wrote it or otherwise have the right to |
| 271 | pass it on as a open-source patch. The rules are pretty simple: if you |
| 272 | can certify the below: |
| 273 | |
Linus Torvalds | cbd83da | 2005-06-13 17:51:55 -0700 | [diff] [blame] | 274 | Developer's Certificate of Origin 1.1 |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 275 | |
| 276 | By making a contribution to this project, I certify that: |
| 277 | |
| 278 | (a) The contribution was created in whole or in part by me and I |
| 279 | have the right to submit it under the open source license |
| 280 | indicated in the file; or |
| 281 | |
| 282 | (b) The contribution is based upon previous work that, to the best |
| 283 | of my knowledge, is covered under an appropriate open source |
| 284 | license and I have the right under that license to submit that |
| 285 | work with modifications, whether created in whole or in part |
| 286 | by me, under the same open source license (unless I am |
| 287 | permitted to submit under a different license), as indicated |
| 288 | in the file; or |
| 289 | |
| 290 | (c) The contribution was provided directly to me by some other |
| 291 | person who certified (a), (b) or (c) and I have not modified |
| 292 | it. |
| 293 | |
Linus Torvalds | cbd83da | 2005-06-13 17:51:55 -0700 | [diff] [blame] | 294 | (d) I understand and agree that this project and the contribution |
| 295 | are public and that a record of the contribution (including all |
| 296 | personal information I submit with it, including my sign-off) is |
| 297 | maintained indefinitely and may be redistributed consistent with |
| 298 | this project or the open source license(s) involved. |
| 299 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 300 | then you just add a line saying |
| 301 | |
| 302 | Signed-off-by: Random J Developer <random@developer.org> |
| 303 | |
| 304 | Some people also put extra tags at the end. They'll just be ignored for |
| 305 | now, but you can do this to mark internal company procedures or just |
| 306 | point out some special detail about the sign-off. |
| 307 | |
| 308 | |
| 309 | ----------------------------------- |
| 310 | SECTION 2 - HINTS, TIPS, AND TRICKS |
| 311 | ----------------------------------- |
| 312 | |
| 313 | This section lists many of the common "rules" associated with code |
| 314 | submitted to the kernel. There are always exceptions... but you must |
| 315 | have a really good reason for doing so. You could probably call this |
| 316 | section Linus Computer Science 101. |
| 317 | |
| 318 | |
| 319 | |
| 320 | 1) Read Documentation/CodingStyle |
| 321 | |
| 322 | Nuff said. If your code deviates too much from this, it is likely |
| 323 | to be rejected without further review, and without comment. |
| 324 | |
| 325 | |
| 326 | |
| 327 | 2) #ifdefs are ugly |
| 328 | |
| 329 | Code cluttered with ifdefs is difficult to read and maintain. Don't do |
| 330 | it. Instead, put your ifdefs in a header, and conditionally define |
| 331 | 'static inline' functions, or macros, which are used in the code. |
| 332 | Let the compiler optimize away the "no-op" case. |
| 333 | |
| 334 | Simple example, of poor code: |
| 335 | |
| 336 | dev = alloc_etherdev (sizeof(struct funky_private)); |
| 337 | if (!dev) |
| 338 | return -ENODEV; |
| 339 | #ifdef CONFIG_NET_FUNKINESS |
| 340 | init_funky_net(dev); |
| 341 | #endif |
| 342 | |
| 343 | Cleaned-up example: |
| 344 | |
| 345 | (in header) |
| 346 | #ifndef CONFIG_NET_FUNKINESS |
| 347 | static inline void init_funky_net (struct net_device *d) {} |
| 348 | #endif |
| 349 | |
| 350 | (in the code itself) |
| 351 | dev = alloc_etherdev (sizeof(struct funky_private)); |
| 352 | if (!dev) |
| 353 | return -ENODEV; |
| 354 | init_funky_net(dev); |
| 355 | |
| 356 | |
| 357 | |
| 358 | 3) 'static inline' is better than a macro |
| 359 | |
| 360 | Static inline functions are greatly preferred over macros. |
| 361 | They provide type safety, have no length limitations, no formatting |
| 362 | limitations, and under gcc they are as cheap as macros. |
| 363 | |
| 364 | Macros should only be used for cases where a static inline is clearly |
| 365 | suboptimal [there a few, isolated cases of this in fast paths], |
| 366 | or where it is impossible to use a static inline function [such as |
| 367 | string-izing]. |
| 368 | |
| 369 | 'static inline' is preferred over 'static __inline__', 'extern inline', |
| 370 | and 'extern __inline__'. |
| 371 | |
| 372 | |
| 373 | |
| 374 | 4) Don't over-design. |
| 375 | |
| 376 | Don't try to anticipate nebulous future cases which may or may not |
| 377 | be useful: "Make it as simple as you can, and no simpler" |
| 378 | |
| 379 | |
| 380 | |