Documentation/SubmittingPatches

   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 -u"
  24 ------------
  25
  26 Use "diff -u" or "diff -urN" 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 Patches should be based in the root kernel source directory, not in
  32 any lower subdirectory.
  33
  34 To create a patch for a single file, it is often sufficient to do:
  35
  36         SRCTREE= /devel/linux-2.4
  37         MYFILE=  drivers/net/mydriver.c
  38
  39         cd $SRCTREE
  40         cp $MYFILE $MYFILE.orig
  41         vi $MYFILE      # make your change
  42         diff -u $MYFILE.orig $MYFILE > /tmp/patch
  43
  44 To create a patch for multiple files, you should unpack a "vanilla",
  45 or unmodified kernel source tree, and generate a diff against your
  46 own source tree.  For example:
  47
  48         MYSRC= /devel/linux-2.4
  49
  50         tar xvfz linux-2.4.0-test11.tar.gz
  51         mv linux linux-vanilla
  52         wget http://www.moses.uklinux.net/patches/dontdiff
  53         diff -urN -X dontdiff linux-vanilla $MYSRC > /tmp/patch
  54         rm -f dontdiff
  55
  56 "dontdiff" is a list of files which are generated by the kernel during
  57 the build process, and should be ignored in any diff(1)-generated
  58 patch.  dontdiff is maintained by Tigran Aivazian <tigran@veritas.com>
  59
  60 Make sure your patch does not include any extra files which do not
  61 belong in a patch submission.  Make sure to review your patch -after-
  62 generated it with diff(1), to ensure accuracy.
  63
  64
  65 2) Describe your changes.
  66
  67 Describe the technical detail of the change(s) your patch includes.
  68
  69 Be as specific as possible.  The WORST descriptions possible include
  70 things like "update driver X", "bug fix for driver X", or "this patch
  71 includes updates for subsystem X.  Please apply."
  72
  73 If your description starts to get long, that's a sign that you probably
  74 need to split up your patch.  See #3, next.
  75
  76
  77
  78 3) Separate your changes.
  79
  80 Separate each logical change into its own patch.
  81
  82 For example, if your changes include both bug fixes and performance
  83 enhancements for a single driver, separate those changes into two
  84 or more patches.  If your changes include an API update, and a new
  85 driver which uses that new API, separate those into two patches.
  86
  87 On the other hand, if you make a single change to numerous files,
  88 group those changes into a single patch.  Thus a single logical change
  89 is contained within a single patch.
  90
  91 If one patch depends on another patch in order for a change to be
  92 complete, that is OK.  Simply note "this patch depends on patch X"
  93 in your patch description.
  94
  95
  96 4) Select e-mail destination.
  97
  98 Look through the MAINTAINERS file and the source code, and determine
  99 if your change applies to a specific subsystem of the kernel, with
 100 an assigned maintainer.  If so, e-mail that person.
 101
 102 If no maintainer is listed, or the maintainer does not respond, send
 103 your patch to the primary Linux kernel developer's mailing list,
 104 linux-kernel@vger.kernel.org.  Most kernel developers monitor this
 105 e-mail list, and can comment on your changes.
 106
 107 Linus Torvalds is the final arbiter of all changes accepted into the
 108 Linux kernel.  His e-mail address is torvalds@transmeta.com.  He gets
 109 a lot of e-mail, so typically you should do your best to -avoid- sending
 110 him e-mail.
 111
 112 Patches which are bug fixes, are "obvious" changes, or similarly
 113 require little discussion should be sent or CC'd to Linus.  Patches
 114 which require discussion or do not have a clear advantage should
 115 usually be sent first to linux-kernel.  Only after the patch is
 116 discussed should the patch then be submitted to Linus.
 117
 118
 119
 120 5) Select your CC (e-mail carbon copy) list.
 121
 122 Unless you have a reason NOT to do so, CC linux-kernel@vger.kernel.org.
 123
 124 Other kernel developers besides Linus need to be aware of your change,
 125 so that they may comment on it and offer code review and suggestions.
 126 linux-kernel is the primary Linux kernel developer mailing list.
 127 Other mailing lists are available for specific subsystems, such as
 128 USB, framebuffer devices, the VFS, the SCSI subsystem, etc.  See the
 129 MAINTAINERS file for a mailing list that relates specifically to
 130 your change.
 131
 132 Even if the maintainer did not respond in step #4, make sure to ALWAYS
 133 copy the maintainer when you change their code.
 134
 135
 136
 137 6) No MIME, no links, no compression, no attachments.  Just plain text.
 138
 139 Linus and other kernel developers need to be able to read and comment
 140 on the changes you are submitting.  It is important for a kernel
 141 developer to be able to "quote" your changes, using standard e-mail
 142 tools, so that they may comment on specific portions of your code.
 143
 144 For this reason, all patches should be submitting e-mail "inline".
 145 WARNING:  Be wary of your editor's word-wrap corrupting your patch,
 146 if you choose to cut-n-paste your patch.
 147
 148 Do not attach the patch as a MIME attachment, compressed or not.
 149 Many popular e-mail applications will not always transmit a MIME
 150 attachment as plain text, making it impossible to comment on your
 151 code.  A MIME attachment also takes Linus a bit more time to process,
 152 decreasing the likelihood of your MIME-attached change being accepted.
 153
 154 Exception:  If your mailer is mangling patches then someone may ask
 155 you to re-send them using MIME.
 156
 157
 158
 159 7) E-mail size.
 160
 161 When sending patches to Linus, always follow step #6.
 162
 163 Large changes are not appropriate for mailing lists, and some
 164 maintainers.  If your patch, uncompressed, exceeds 40 kB in size,
 165 it is preferred that you store your patch on an Internet-accessible
 166 server, and provide instead a URL (link) pointing to your patch.
 167
 168
 169
 170 8) Name your kernel version.
 171
 172 It is important to note, either in the subject line or in the patch
 173 description, the kernel version to which this patch applies.
 174
 175 If the patch does not apply cleanly to the latest kernel version,
 176 Linus will not apply it.
 177
 178
 179
 180 9) Don't get discouraged.  Re-submit.
 181
 182 After you have submitted your change, be patient and wait.  If Linus
 183 likes your change and applies it, it will appear in the next version
 184 of the kernel that he releases.
 185
 186 However, if your change doesn't appear in the next version of the
 187 kernel, there could be any number of reasons.  It's YOUR job to
 188 narrow down those reasons, correct what was wrong, and submit your
 189 updated change.
 190
 191 It is quite common for Linus to "drop" your patch without comment.
 192 That's the nature of the system.  If he drops your patch, it could be
 193 due to
 194 * Your patch did not apply cleanly to the latest kernel version
 195 * Your patch was not sufficiently discussed on linux-kernel.
 196 * A style issue (see section 2),
 197 * An e-mail formatting issue (re-read this section)
 198 * A technical problem with your change
 199 * He gets tons of e-mail, and yours got lost in the shuffle
 200 * You are being annoying (See Figure 1)
 201
 202 When in doubt, solicit comments on linux-kernel mailing list.
 203
 204
 205
 206 10) Include PATCH in the subject
 207
 208 Due to high e-mail traffic to Linus, and to linux-kernel, it is common
 209 convention to prefix your subject line with [PATCH].  This lets Linus
 210 and other kernel developers more easily distinguish patches from other
 211 e-mail discussions.
 212
 213
 214
 215 -----------------------------------
 216 SECTION 2 - HINTS, TIPS, AND TRICKS
 217 -----------------------------------
 218
 219 This section lists many of the common "rules" associated with code
 220 submitted to the kernel.  There are always exceptions... but you must
 221 have a really good reason for doing so.  You could probably call this
 222 section Linus Computer Science 101.
 223
 224
 225
 226 1) Read Documentation/CodingStyle
 227
 228 Nuff said.  If your code deviates too much from this, it is likely
 229 to be rejected without further review, and without comment.
 230
 231
 232
 233 2) #ifdefs are ugly
 234
 235 Code cluttered with ifdefs is difficult to read and maintain.  Don't do
 236 it.  Instead, put your ifdefs in a header, and conditionally define
 237 'static inline' functions, or macros, which are used in the code.
 238 Let the compiler optimize away the "no-op" case.
 239
 240 Simple example, of poor code:
 241
 242         dev = init_etherdev (NULL, 0);
 243         if (!dev)
 244                 return -ENODEV;
 245         #ifdef CONFIG_NET_FUNKINESS
 246                 init_funky_net(dev);
 247         #endif
 248
 249 Cleaned-up example:
 250
 251 (in header)
 252         #ifndef CONFIG_NET_FUNKINESS
 253         static inline void init_funky_net (struct net_device *d) {}
 254         #endif
 255
 256 (in the code itself)
 257         dev = init_etherdev (NULL, 0);
 258         if (!dev)
 259                 return -ENODEV;
 260         init_funky_net(dev);
 261
 262
 263
 264 3) 'static inline' is better than a macro
 265
 266 Static inline functions are greatly preferred over macros.
 267 They provide type safety, have no length limitations, no formatting
 268 limitations, and under gcc they are as cheap as macros.
 269
 270 Macros should only be used for cases where a static inline is clearly
 271 suboptimal [there a few, isolated cases of this in fast paths],
 272 or where it is impossible to use a static inline function [such as
 273 string-izing].
 274
 275 'static inline' is preferred over 'static __inline__', 'extern inline',
 276 and 'extern __inline__'.
 277
 278
 279
 280 4) Don't over-design.
 281
 282 Don't try to anticipate nebulous future cases which may or may not
 283 be useful:  "Make it as simple as you can, and no simpler"
 284
 285
 286