1 This file has moved to process/submitting-patc !! 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@osdl.org>. 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
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.