blob: bcdeee146ff1dc74e46a9ec2b2d9757186cfdac2 [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001
2 How to Get Your Change Into the Linux Kernel
3 or
4 Care And Operation Of Your Linus Torvalds
5
6
7
8For a person or company who wishes to submit a change to the Linux
9kernel, the process can sometimes be daunting if you're not familiar
10with "the system." This text is a collection of suggestions which
11can greatly increase the chances of your change being accepted.
12
13If you are submitting a driver, also read Documentation/SubmittingDrivers.
14
15
16
17--------------------------------------------
18SECTION 1 - CREATING AND SENDING YOUR CHANGE
19--------------------------------------------
20
21
22
231) "diff -up"
24------------
25
26Use "diff -up" or "diff -uprN" to create patches.
27
28All changes to the Linux kernel occur in the form of patches, as
29generated by diff(1). When creating your patch, make sure to create it
30in "unified diff" format, as supplied by the '-u' argument to diff(1).
31Also, please use the '-p' argument which shows which C function each
32change is in - that makes the resultant diff a lot easier to read.
33Patches should be based in the root kernel source directory,
34not in any lower subdirectory.
35
36To 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
47To create a patch for multiple files, you should unpack a "vanilla",
48or unmodified kernel source tree, and generate a diff against your
49own 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
60the build process, and should be ignored in any diff(1)-generated
61patch. dontdiff is maintained by Tigran Aivazian <tigran@veritas.com>
62
63Make sure your patch does not include any extra files which do not
64belong in a patch submission. Make sure to review your patch -after-
65generated it with diff(1), to ensure accuracy.
66
67If your changes produce a lot of deltas, you may want to look into
68splitting them into individual patches which modify things in
69logical stages, this will facilitate easier reviewing by other
70kernel developers, very important if you want your patch accepted.
71There are a number of scripts which can aid in this;
72
73Quilt:
74http://savannah.nongnu.org/projects/quilt
75
76Randy Dunlap's patch scripts:
77http://developer.osdl.org/rddunlap/scripts/patching-scripts.tgz
78
79Andrew Morton's patch scripts:
80http://www.zip.com.au/~akpm/linux/patches/patch-scripts-0.16
81
822) Describe your changes.
83
84Describe the technical detail of the change(s) your patch includes.
85
86Be as specific as possible. The WORST descriptions possible include
87things like "update driver X", "bug fix for driver X", or "this patch
88includes updates for subsystem X. Please apply."
89
90If your description starts to get long, that's a sign that you probably
91need to split up your patch. See #3, next.
92
93
94
953) Separate your changes.
96
97Separate each logical change into its own patch.
98
99For example, if your changes include both bug fixes and performance
100enhancements for a single driver, separate those changes into two
101or more patches. If your changes include an API update, and a new
102driver which uses that new API, separate those into two patches.
103
104On the other hand, if you make a single change to numerous files,
105group those changes into a single patch. Thus a single logical change
106is contained within a single patch.
107
108If one patch depends on another patch in order for a change to be
109complete, that is OK. Simply note "this patch depends on patch X"
110in your patch description.
111
112
1134) Select e-mail destination.
114
115Look through the MAINTAINERS file and the source code, and determine
116if your change applies to a specific subsystem of the kernel, with
117an assigned maintainer. If so, e-mail that person.
118
119If no maintainer is listed, or the maintainer does not respond, send
120your patch to the primary Linux kernel developer's mailing list,
121linux-kernel@vger.kernel.org. Most kernel developers monitor this
122e-mail list, and can comment on your changes.
123
124Linus Torvalds is the final arbiter of all changes accepted into the
125Linux kernel. His e-mail address is <torvalds@osdl.org>. He gets
126a lot of e-mail, so typically you should do your best to -avoid- sending
127him e-mail.
128
129Patches which are bug fixes, are "obvious" changes, or similarly
130require little discussion should be sent or CC'd to Linus. Patches
131which require discussion or do not have a clear advantage should
132usually be sent first to linux-kernel. Only after the patch is
133discussed should the patch then be submitted to Linus.
134
135For small patches you may want to CC the Trivial Patch Monkey
136trivial@rustcorp.com.au set up by Rusty Russell; which collects "trivial"
137patches. 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
1525) Select your CC (e-mail carbon copy) list.
153
154Unless you have a reason NOT to do so, CC linux-kernel@vger.kernel.org.
155
156Other kernel developers besides Linus need to be aware of your change,
157so that they may comment on it and offer code review and suggestions.
158linux-kernel is the primary Linux kernel developer mailing list.
159Other mailing lists are available for specific subsystems, such as
160USB, framebuffer devices, the VFS, the SCSI subsystem, etc. See the
161MAINTAINERS file for a mailing list that relates specifically to
162your change.
163
164Even if the maintainer did not respond in step #4, make sure to ALWAYS
165copy the maintainer when you change their code.
166
167For small patches you may want to CC the Trivial Patch Monkey
168trivial@rustcorp.com.au set up by Rusty Russell; which collects "trivial"
169patches. 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
1846) No MIME, no links, no compression, no attachments. Just plain text.
185
186Linus and other kernel developers need to be able to read and comment
187on the changes you are submitting. It is important for a kernel
188developer to be able to "quote" your changes, using standard e-mail
189tools, so that they may comment on specific portions of your code.
190
191For this reason, all patches should be submitting e-mail "inline".
192WARNING: Be wary of your editor's word-wrap corrupting your patch,
193if you choose to cut-n-paste your patch.
194
195Do not attach the patch as a MIME attachment, compressed or not.
196Many popular e-mail applications will not always transmit a MIME
197attachment as plain text, making it impossible to comment on your
198code. A MIME attachment also takes Linus a bit more time to process,
199decreasing the likelihood of your MIME-attached change being accepted.
200
201Exception: If your mailer is mangling patches then someone may ask
202you to re-send them using MIME.
203
204
205
2067) E-mail size.
207
208When sending patches to Linus, always follow step #6.
209
210Large changes are not appropriate for mailing lists, and some
211maintainers. If your patch, uncompressed, exceeds 40 kB in size,
212it is preferred that you store your patch on an Internet-accessible
213server, and provide instead a URL (link) pointing to your patch.
214
215
216
2178) Name your kernel version.
218
219It is important to note, either in the subject line or in the patch
220description, the kernel version to which this patch applies.
221
222If the patch does not apply cleanly to the latest kernel version,
223Linus will not apply it.
224
225
226
2279) Don't get discouraged. Re-submit.
228
229After you have submitted your change, be patient and wait. If Linus
230likes your change and applies it, it will appear in the next version
231of the kernel that he releases.
232
233However, if your change doesn't appear in the next version of the
234kernel, there could be any number of reasons. It's YOUR job to
235narrow down those reasons, correct what was wrong, and submit your
236updated change.
237
238It is quite common for Linus to "drop" your patch without comment.
239That's the nature of the system. If he drops your patch, it could be
240due 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
249When in doubt, solicit comments on linux-kernel mailing list.
250
251
252
25310) Include PATCH in the subject
254
255Due to high e-mail traffic to Linus, and to linux-kernel, it is common
256convention to prefix your subject line with [PATCH]. This lets Linus
257and other kernel developers more easily distinguish patches from other
258e-mail discussions.
259
260
261
26211) Sign your work
263
264To improve tracking of who did what, especially with patches that can
265percolate to their final resting place in the kernel through several
266layers of maintainers, we've introduced a "sign-off" procedure on
267patches that are being emailed around.
268
269The sign-off is a simple line at the end of the explanation for the
270patch, which certifies that you wrote it or otherwise have the right to
271pass it on as a open-source patch. The rules are pretty simple: if you
272can certify the below:
273
Linus Torvaldscbd83da2005-06-13 17:51:55 -0700274 Developer's Certificate of Origin 1.1
Linus Torvalds1da177e2005-04-16 15:20:36 -0700275
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 Torvaldscbd83da2005-06-13 17:51:55 -0700294 (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 Torvalds1da177e2005-04-16 15:20:36 -0700300then you just add a line saying
301
Alexey Dobriyan9fd55592005-06-25 14:59:34 -0700302 Signed-off-by: Random J Developer <random@developer.example.org>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700303
304Some people also put extra tags at the end. They'll just be ignored for
305now, but you can do this to mark internal company procedures or just
306point out some special detail about the sign-off.
307
308
309-----------------------------------
310SECTION 2 - HINTS, TIPS, AND TRICKS
311-----------------------------------
312
313This section lists many of the common "rules" associated with code
314submitted to the kernel. There are always exceptions... but you must
315have a really good reason for doing so. You could probably call this
316section Linus Computer Science 101.
317
318
319
3201) Read Documentation/CodingStyle
321
322Nuff said. If your code deviates too much from this, it is likely
323to be rejected without further review, and without comment.
324
325
326
3272) #ifdefs are ugly
328
329Code cluttered with ifdefs is difficult to read and maintain. Don't do
330it. Instead, put your ifdefs in a header, and conditionally define
331'static inline' functions, or macros, which are used in the code.
332Let the compiler optimize away the "no-op" case.
333
334Simple 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
343Cleaned-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
3583) 'static inline' is better than a macro
359
360Static inline functions are greatly preferred over macros.
361They provide type safety, have no length limitations, no formatting
362limitations, and under gcc they are as cheap as macros.
363
364Macros should only be used for cases where a static inline is clearly
365suboptimal [there a few, isolated cases of this in fast paths],
366or where it is impossible to use a static inline function [such as
367string-izing].
368
369'static inline' is preferred over 'static __inline__', 'extern inline',
370and 'extern __inline__'.
371
372
373
3744) Don't over-design.
375
376Don't try to anticipate nebulous future cases which may or may not
377be useful: "Make it as simple as you can, and no simpler"
378
379
380