Commit | Line | Data |
---|---|---|
d36cc9d0 GKH |
1 | HOWTO do Linux kernel development |
2 | --------------------------------- | |
3 | ||
4 | This is the be-all, end-all document on this topic. It contains | |
5 | instructions on how to become a Linux kernel developer and how to learn | |
6 | to work with the Linux kernel development community. It tries to not | |
7 | contain anything related to the technical aspects of kernel programming, | |
8 | but will help point you in the right direction for that. | |
9 | ||
10 | If anything in this document becomes out of date, please send in patches | |
11 | to the maintainer of this file, who is listed at the bottom of the | |
12 | document. | |
13 | ||
14 | ||
15 | Introduction | |
16 | ------------ | |
17 | ||
18 | So, you want to learn how to become a Linux kernel developer? Or you | |
19 | have been told by your manager, "Go write a Linux driver for this | |
20 | device." This document's goal is to teach you everything you need to | |
21 | know to achieve this by describing the process you need to go through, | |
22 | and hints on how to work with the community. It will also try to | |
23 | explain some of the reasons why the community works like it does. | |
24 | ||
25 | The kernel is written mostly in C, with some architecture-dependent | |
26 | parts written in assembly. A good understanding of C is required for | |
27 | kernel development. Assembly (any architecture) is not required unless | |
28 | you plan to do low-level development for that architecture. Though they | |
29 | are not a good substitute for a solid C education and/or years of | |
30 | experience, the following books are good for, if anything, reference: | |
31 | - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall] | |
32 | - "Practical C Programming" by Steve Oualline [O'Reilly] | |
4de0ca81 | 33 | - "C: A Reference Manual" by Harbison and Steele [Prentice Hall] |
d36cc9d0 GKH |
34 | |
35 | The kernel is written using GNU C and the GNU toolchain. While it | |
36 | adheres to the ISO C89 standard, it uses a number of extensions that are | |
37 | not featured in the standard. The kernel is a freestanding C | |
38 | environment, with no reliance on the standard C library, so some | |
39 | portions of the C standard are not supported. Arbitrary long long | |
40 | divisions and floating point are not allowed. It can sometimes be | |
41 | difficult to understand the assumptions the kernel has on the toolchain | |
42 | and the extensions that it uses, and unfortunately there is no | |
43 | definitive reference for them. Please check the gcc info pages (`info | |
44 | gcc`) for some information on them. | |
45 | ||
46 | Please remember that you are trying to learn how to work with the | |
47 | existing development community. It is a diverse group of people, with | |
48 | high standards for coding, style and procedure. These standards have | |
49 | been created over time based on what they have found to work best for | |
50 | such a large and geographically dispersed team. Try to learn as much as | |
51 | possible about these standards ahead of time, as they are well | |
52 | documented; do not expect people to adapt to you or your company's way | |
53 | of doing things. | |
54 | ||
55 | ||
56 | Legal Issues | |
57 | ------------ | |
58 | ||
59 | The Linux kernel source code is released under the GPL. Please see the | |
60 | file, COPYING, in the main directory of the source tree, for details on | |
61 | the license. If you have further questions about the license, please | |
62 | contact a lawyer, and do not ask on the Linux kernel mailing list. The | |
63 | people on the mailing lists are not lawyers, and you should not rely on | |
64 | their statements on legal matters. | |
65 | ||
66 | For common questions and answers about the GPL, please see: | |
67 | http://www.gnu.org/licenses/gpl-faq.html | |
68 | ||
69 | ||
70 | Documentation | |
71 | ------------ | |
72 | ||
73 | The Linux kernel source tree has a large range of documents that are | |
74 | invaluable for learning how to interact with the kernel community. When | |
75 | new features are added to the kernel, it is recommended that new | |
76 | documentation files are also added which explain how to use the feature. | |
77 | When a kernel change causes the interface that the kernel exposes to | |
78 | userspace to change, it is recommended that you send the information or | |
79 | a patch to the manual pages explaining the change to the manual pages | |
80 | maintainer at mtk-manpages@gmx.net. | |
81 | ||
82 | Here is a list of files that are in the kernel source tree that are | |
83 | required reading: | |
84 | README | |
85 | This file gives a short background on the Linux kernel and describes | |
86 | what is necessary to do to configure and build the kernel. People | |
87 | who are new to the kernel should start here. | |
88 | ||
89 | Documentation/Changes | |
90 | This file gives a list of the minimum levels of various software | |
91 | packages that are necessary to build and run the kernel | |
92 | successfully. | |
93 | ||
94 | Documentation/CodingStyle | |
95 | This describes the Linux kernel coding style, and some of the | |
96 | rationale behind it. All new code is expected to follow the | |
97 | guidelines in this document. Most maintainers will only accept | |
98 | patches if these rules are followed, and many people will only | |
99 | review code if it is in the proper style. | |
100 | ||
101 | Documentation/SubmittingPatches | |
102 | Documentation/SubmittingDrivers | |
103 | These files describe in explicit detail how to successfully create | |
104 | and send a patch, including (but not limited to): | |
105 | - Email contents | |
106 | - Email format | |
107 | - Who to send it to | |
108 | Following these rules will not guarantee success (as all patches are | |
109 | subject to scrutiny for content and style), but not following them | |
110 | will almost always prevent it. | |
111 | ||
112 | Other excellent descriptions of how to create patches properly are: | |
113 | "The Perfect Patch" | |
114 | http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt | |
115 | "Linux kernel patch submission format" | |
116 | http://linux.yyz.us/patch-format.html | |
117 | ||
118 | Documentation/stable_api_nonsense.txt | |
119 | This file describes the rationale behind the conscious decision to | |
120 | not have a stable API within the kernel, including things like: | |
121 | - Subsystem shim-layers (for compatibility?) | |
122 | - Driver portability between Operating Systems. | |
123 | - Mitigating rapid change within the kernel source tree (or | |
124 | preventing rapid change) | |
125 | This document is crucial for understanding the Linux development | |
126 | philosophy and is very important for people moving to Linux from | |
127 | development on other Operating Systems. | |
128 | ||
129 | Documentation/SecurityBugs | |
130 | If you feel you have found a security problem in the Linux kernel, | |
131 | please follow the steps in this document to help notify the kernel | |
132 | developers, and help solve the issue. | |
133 | ||
134 | Documentation/ManagementStyle | |
135 | This document describes how Linux kernel maintainers operate and the | |
136 | shared ethos behind their methodologies. This is important reading | |
137 | for anyone new to kernel development (or anyone simply curious about | |
138 | it), as it resolves a lot of common misconceptions and confusion | |
139 | about the unique behavior of kernel maintainers. | |
140 | ||
141 | Documentation/stable_kernel_rules.txt | |
142 | This file describes the rules on how the stable kernel releases | |
143 | happen, and what to do if you want to get a change into one of these | |
144 | releases. | |
145 | ||
146 | Documentation/kernel-docs.txt | |
147 | A list of external documentation that pertains to kernel | |
148 | development. Please consult this list if you do not find what you | |
149 | are looking for within the in-kernel documentation. | |
150 | ||
151 | Documentation/applying-patches.txt | |
152 | A good introduction describing exactly what a patch is and how to | |
153 | apply it to the different development branches of the kernel. | |
154 | ||
155 | The kernel also has a large number of documents that can be | |
156 | automatically generated from the source code itself. This includes a | |
157 | full description of the in-kernel API, and rules on how to handle | |
158 | locking properly. The documents will be created in the | |
159 | Documentation/DocBook/ directory and can be generated as PDF, | |
160 | Postscript, HTML, and man pages by running: | |
161 | make pdfdocs | |
162 | make psdocs | |
163 | make htmldocs | |
164 | make mandocs | |
165 | respectively from the main kernel source directory. | |
166 | ||
167 | ||
168 | Becoming A Kernel Developer | |
169 | --------------------------- | |
170 | ||
171 | If you do not know anything about Linux kernel development, you should | |
172 | look at the Linux KernelNewbies project: | |
173 | http://kernelnewbies.org | |
174 | It consists of a helpful mailing list where you can ask almost any type | |
175 | of basic kernel development question (make sure to search the archives | |
176 | first, before asking something that has already been answered in the | |
177 | past.) It also has an IRC channel that you can use to ask questions in | |
178 | real-time, and a lot of helpful documentation that is useful for | |
179 | learning about Linux kernel development. | |
180 | ||
181 | The website has basic information about code organization, subsystems, | |
182 | and current projects (both in-tree and out-of-tree). It also describes | |
183 | some basic logistical information, like how to compile a kernel and | |
184 | apply a patch. | |
185 | ||
186 | If you do not know where you want to start, but you want to look for | |
187 | some task to start doing to join into the kernel development community, | |
188 | go to the Linux Kernel Janitor's project: | |
189 | http://janitor.kernelnewbies.org/ | |
190 | It is a great place to start. It describes a list of relatively simple | |
191 | problems that need to be cleaned up and fixed within the Linux kernel | |
192 | source tree. Working with the developers in charge of this project, you | |
193 | will learn the basics of getting your patch into the Linux kernel tree, | |
194 | and possibly be pointed in the direction of what to go work on next, if | |
195 | you do not already have an idea. | |
196 | ||
197 | If you already have a chunk of code that you want to put into the kernel | |
198 | tree, but need some help getting it in the proper form, the | |
199 | kernel-mentors project was created to help you out with this. It is a | |
200 | mailing list, and can be found at: | |
201 | http://selenic.com/mailman/listinfo/kernel-mentors | |
202 | ||
203 | Before making any actual modifications to the Linux kernel code, it is | |
204 | imperative to understand how the code in question works. For this | |
205 | purpose, nothing is better than reading through it directly (most tricky | |
206 | bits are commented well), perhaps even with the help of specialized | |
207 | tools. One such tool that is particularly recommended is the Linux | |
208 | Cross-Reference project, which is able to present source code in a | |
209 | self-referential, indexed webpage format. An excellent up-to-date | |
210 | repository of the kernel code may be found at: | |
211 | http://sosdg.org/~coywolf/lxr/ | |
212 | ||
213 | ||
214 | The development process | |
215 | ----------------------- | |
216 | ||
217 | Linux kernel development process currently consists of a few different | |
218 | main kernel "branches" and lots of different subsystem-specific kernel | |
219 | branches. These different branches are: | |
220 | - main 2.6.x kernel tree | |
221 | - 2.6.x.y -stable kernel tree | |
222 | - 2.6.x -git kernel patches | |
223 | - 2.6.x -mm kernel patches | |
224 | - subsystem specific kernel trees and patches | |
225 | ||
226 | 2.6.x kernel tree | |
227 | ----------------- | |
228 | 2.6.x kernels are maintained by Linus Torvalds, and can be found on | |
229 | kernel.org in the pub/linux/kernel/v2.6/ directory. Its development | |
230 | process is as follows: | |
231 | - As soon as a new kernel is released a two weeks window is open, | |
232 | during this period of time maintainers can submit big diffs to | |
233 | Linus, usually the patches that have already been included in the | |
234 | -mm kernel for a few weeks. The preferred way to submit big changes | |
235 | is using git (the kernel's source management tool, more information | |
236 | can be found at http://git.or.cz/) but plain patches are also just | |
237 | fine. | |
238 | - After two weeks a -rc1 kernel is released it is now possible to push | |
239 | only patches that do not include new features that could affect the | |
240 | stability of the whole kernel. Please note that a whole new driver | |
241 | (or filesystem) might be accepted after -rc1 because there is no | |
242 | risk of causing regressions with such a change as long as the change | |
243 | is self-contained and does not affect areas outside of the code that | |
244 | is being added. git can be used to send patches to Linus after -rc1 | |
245 | is released, but the patches need to also be sent to a public | |
246 | mailing list for review. | |
247 | - A new -rc is released whenever Linus deems the current git tree to | |
248 | be in a reasonably sane state adequate for testing. The goal is to | |
249 | release a new -rc kernel every week. | |
250 | - Process continues until the kernel is considered "ready", the | |
251 | process should last around 6 weeks. | |
252 | ||
253 | It is worth mentioning what Andrew Morton wrote on the linux-kernel | |
254 | mailing list about kernel releases: | |
255 | "Nobody knows when a kernel will be released, because it's | |
256 | released according to perceived bug status, not according to a | |
257 | preconceived timeline." | |
258 | ||
259 | 2.6.x.y -stable kernel tree | |
260 | --------------------------- | |
261 | Kernels with 4 digit versions are -stable kernels. They contain | |
262 | relatively small and critical fixes for security problems or significant | |
263 | regressions discovered in a given 2.6.x kernel. | |
264 | ||
265 | This is the recommended branch for users who want the most recent stable | |
266 | kernel and are not interested in helping test development/experimental | |
267 | versions. | |
268 | ||
269 | If no 2.6.x.y kernel is available, then the highest numbered 2.6.x | |
270 | kernel is the current stable kernel. | |
271 | ||
272 | 2.6.x.y are maintained by the "stable" team <stable@kernel.org>, and are | |
273 | released almost every other week. | |
274 | ||
275 | The file Documentation/stable_kernel_rules.txt in the kernel tree | |
276 | documents what kinds of changes are acceptable for the -stable tree, and | |
277 | how the release process works. | |
278 | ||
279 | 2.6.x -git patches | |
280 | ------------------ | |
281 | These are daily snapshots of Linus' kernel tree which are managed in a | |
282 | git repository (hence the name.) These patches are usually released | |
283 | daily and represent the current state of Linus' tree. They are more | |
284 | experimental than -rc kernels since they are generated automatically | |
285 | without even a cursory glance to see if they are sane. | |
286 | ||
287 | 2.6.x -mm kernel patches | |
288 | ------------------------ | |
289 | These are experimental kernel patches released by Andrew Morton. Andrew | |
290 | takes all of the different subsystem kernel trees and patches and mushes | |
291 | them together, along with a lot of patches that have been plucked from | |
292 | the linux-kernel mailing list. This tree serves as a proving ground for | |
293 | new features and patches. Once a patch has proved its worth in -mm for | |
294 | a while Andrew or the subsystem maintainer pushes it on to Linus for | |
295 | inclusion in mainline. | |
296 | ||
297 | It is heavily encouraged that all new patches get tested in the -mm tree | |
298 | before they are sent to Linus for inclusion in the main kernel tree. | |
299 | ||
300 | These kernels are not appropriate for use on systems that are supposed | |
301 | to be stable and they are more risky to run than any of the other | |
302 | branches. | |
303 | ||
304 | If you wish to help out with the kernel development process, please test | |
305 | and use these kernel releases and provide feedback to the linux-kernel | |
306 | mailing list if you have any problems, and if everything works properly. | |
307 | ||
308 | In addition to all the other experimental patches, these kernels usually | |
309 | also contain any changes in the mainline -git kernels available at the | |
310 | time of release. | |
311 | ||
312 | The -mm kernels are not released on a fixed schedule, but usually a few | |
313 | -mm kernels are released in between each -rc kernel (1 to 3 is common). | |
314 | ||
315 | Subsystem Specific kernel trees and patches | |
316 | ------------------------------------------- | |
317 | A number of the different kernel subsystem developers expose their | |
318 | development trees so that others can see what is happening in the | |
319 | different areas of the kernel. These trees are pulled into the -mm | |
320 | kernel releases as described above. | |
321 | ||
322 | Here is a list of some of the different kernel trees available: | |
323 | git trees: | |
324 | - Kbuild development tree, Sam Ravnborg <sam@ravnborg.org> | |
325 | kernel.org:/pub/scm/linux/kernel/git/sam/kbuild.git | |
326 | ||
327 | - ACPI development tree, Len Brown <len.brown@intel.com> | |
328 | kernel.org:/pub/scm/linux/kernel/git/lenb/linux-acpi-2.6.git | |
329 | ||
330 | - Block development tree, Jens Axboe <axboe@suse.de> | |
331 | kernel.org:/pub/scm/linux/kernel/git/axboe/linux-2.6-block.git | |
332 | ||
333 | - DRM development tree, Dave Airlie <airlied@linux.ie> | |
334 | kernel.org:/pub/scm/linux/kernel/git/airlied/drm-2.6.git | |
335 | ||
336 | - ia64 development tree, Tony Luck <tony.luck@intel.com> | |
337 | kernel.org:/pub/scm/linux/kernel/git/aegl/linux-2.6.git | |
338 | ||
339 | - ieee1394 development tree, Jody McIntyre <scjody@modernduck.com> | |
340 | kernel.org:/pub/scm/linux/kernel/git/scjody/ieee1394.git | |
341 | ||
342 | - infiniband, Roland Dreier <rolandd@cisco.com> | |
343 | kernel.org:/pub/scm/linux/kernel/git/roland/infiniband.git | |
344 | ||
345 | - libata, Jeff Garzik <jgarzik@pobox.com> | |
346 | kernel.org:/pub/scm/linux/kernel/git/jgarzik/libata-dev.git | |
347 | ||
348 | - network drivers, Jeff Garzik <jgarzik@pobox.com> | |
349 | kernel.org:/pub/scm/linux/kernel/git/jgarzik/netdev-2.6.git | |
350 | ||
351 | - pcmcia, Dominik Brodowski <linux@dominikbrodowski.net> | |
352 | kernel.org:/pub/scm/linux/kernel/git/brodo/pcmcia-2.6.git | |
353 | ||
354 | - SCSI, James Bottomley <James.Bottomley@SteelEye.com> | |
355 | kernel.org:/pub/scm/linux/kernel/git/jejb/scsi-misc-2.6.git | |
356 | ||
357 | Other git kernel trees can be found listed at http://kernel.org/git | |
358 | ||
359 | quilt trees: | |
360 | - USB, PCI, Driver Core, and I2C, Greg Kroah-Hartman <gregkh@suse.de> | |
361 | kernel.org/pub/linux/kernel/people/gregkh/gregkh-2.6/ | |
027a51ce AK |
362 | - x86-64, partly i386, Andi Kleen <ak@suse.de> |
363 | ftp.firstfloor.org:/pub/ak/x86_64/quilt/ | |
d36cc9d0 GKH |
364 | |
365 | Bug Reporting | |
366 | ------------- | |
367 | ||
368 | bugzilla.kernel.org is where the Linux kernel developers track kernel | |
369 | bugs. Users are encouraged to report all bugs that they find in this | |
370 | tool. For details on how to use the kernel bugzilla, please see: | |
371 | http://test.kernel.org/bugzilla/faq.html | |
372 | ||
373 | The file REPORTING-BUGS in the main kernel source directory has a good | |
374 | template for how to report a possible kernel bug, and details what kind | |
375 | of information is needed by the kernel developers to help track down the | |
376 | problem. | |
377 | ||
378 | ||
3f271008 DC |
379 | Managing bug reports |
380 | -------------------- | |
381 | ||
382 | One of the best ways to put into practice your hacking skills is by fixing | |
383 | bugs reported by other people. Not only you will help to make the kernel | |
384 | more stable, you'll learn to fix real world problems and you will improve | |
385 | your skills, and other developers will be aware of your presence. Fixing | |
386 | bugs is one of the best ways to earn merit amongst the developers, because | |
387 | not many people like wasting time fixing other people's bugs. | |
722385f7 DC |
388 | |
389 | To work in the already reported bug reports, go to http://bugzilla.kernel.org. | |
390 | If you want to be advised of the future bug reports, you can subscribe to the | |
391 | bugme-new mailing list (only new bug reports are mailed here) or to the | |
392 | bugme-janitor mailing list (every change in the bugzilla is mailed here) | |
393 | ||
394 | http://lists.osdl.org/mailman/listinfo/bugme-new | |
395 | http://lists.osdl.org/mailman/listinfo/bugme-janitors | |
396 | ||
397 | ||
398 | ||
399 | Managing bug reports | |
400 | -------------------- | |
401 | ||
402 | One of the best ways to put into practice your hacking skills is by fixing | |
403 | bugs reported by other people. Not only you will help to make the kernel | |
404 | more stable, you'll learn to fix real world problems and you will improve | |
405 | your skills, and other developers will be aware of your presence. Fixing | |
406 | bugs is one of the best ways to get merits among other developers, because | |
407 | not many people like wasting time fixing other people's bugs. | |
3f271008 DC |
408 | |
409 | To work in the already reported bug reports, go to http://bugzilla.kernel.org. | |
410 | If you want to be advised of the future bug reports, you can subscribe to the | |
411 | bugme-new mailing list (only new bug reports are mailed here) or to the | |
412 | bugme-janitor mailing list (every change in the bugzilla is mailed here) | |
413 | ||
414 | http://lists.osdl.org/mailman/listinfo/bugme-new | |
415 | http://lists.osdl.org/mailman/listinfo/bugme-janitors | |
416 | ||
417 | ||
418 | ||
d36cc9d0 GKH |
419 | Mailing lists |
420 | ------------- | |
421 | ||
422 | As some of the above documents describe, the majority of the core kernel | |
423 | developers participate on the Linux Kernel Mailing list. Details on how | |
424 | to subscribe and unsubscribe from the list can be found at: | |
425 | http://vger.kernel.org/vger-lists.html#linux-kernel | |
426 | There are archives of the mailing list on the web in many different | |
427 | places. Use a search engine to find these archives. For example: | |
428 | http://dir.gmane.org/gmane.linux.kernel | |
429 | It is highly recommended that you search the archives about the topic | |
430 | you want to bring up, before you post it to the list. A lot of things | |
431 | already discussed in detail are only recorded at the mailing list | |
432 | archives. | |
433 | ||
434 | Most of the individual kernel subsystems also have their own separate | |
435 | mailing list where they do their development efforts. See the | |
436 | MAINTAINERS file for a list of what these lists are for the different | |
437 | groups. | |
438 | ||
439 | Many of the lists are hosted on kernel.org. Information on them can be | |
440 | found at: | |
441 | http://vger.kernel.org/vger-lists.html | |
442 | ||
443 | Please remember to follow good behavioral habits when using the lists. | |
444 | Though a bit cheesy, the following URL has some simple guidelines for | |
445 | interacting with the list (or any list): | |
446 | http://www.albion.com/netiquette/ | |
447 | ||
448 | If multiple people respond to your mail, the CC: list of recipients may | |
449 | get pretty large. Don't remove anybody from the CC: list without a good | |
450 | reason, or don't reply only to the list address. Get used to receiving the | |
451 | mail twice, one from the sender and the one from the list, and don't try | |
452 | to tune that by adding fancy mail-headers, people will not like it. | |
453 | ||
454 | Remember to keep the context and the attribution of your replies intact, | |
455 | keep the "John Kernelhacker wrote ...:" lines at the top of your reply, and | |
456 | add your statements between the individual quoted sections instead of | |
457 | writing at the top of the mail. | |
458 | ||
459 | If you add patches to your mail, make sure they are plain readable text | |
460 | as stated in Documentation/SubmittingPatches. Kernel developers don't | |
461 | want to deal with attachments or compressed patches; they may want | |
462 | to comment on individual lines of your patch, which works only that way. | |
463 | Make sure you use a mail program that does not mangle spaces and tab | |
464 | characters. A good first test is to send the mail to yourself and try | |
465 | to apply your own patch by yourself. If that doesn't work, get your | |
466 | mail program fixed or change it until it works. | |
467 | ||
468 | Above all, please remember to show respect to other subscribers. | |
469 | ||
470 | ||
471 | Working with the community | |
472 | -------------------------- | |
473 | ||
474 | The goal of the kernel community is to provide the best possible kernel | |
475 | there is. When you submit a patch for acceptance, it will be reviewed | |
476 | on its technical merits and those alone. So, what should you be | |
477 | expecting? | |
478 | - criticism | |
479 | - comments | |
480 | - requests for change | |
481 | - requests for justification | |
482 | - silence | |
483 | ||
484 | Remember, this is part of getting your patch into the kernel. You have | |
485 | to be able to take criticism and comments about your patches, evaluate | |
486 | them at a technical level and either rework your patches or provide | |
487 | clear and concise reasoning as to why those changes should not be made. | |
488 | If there are no responses to your posting, wait a few days and try | |
489 | again, sometimes things get lost in the huge volume. | |
490 | ||
491 | What should you not do? | |
492 | - expect your patch to be accepted without question | |
493 | - become defensive | |
494 | - ignore comments | |
495 | - resubmit the patch without making any of the requested changes | |
496 | ||
497 | In a community that is looking for the best technical solution possible, | |
498 | there will always be differing opinions on how beneficial a patch is. | |
499 | You have to be cooperative, and willing to adapt your idea to fit within | |
500 | the kernel. Or at least be willing to prove your idea is worth it. | |
501 | Remember, being wrong is acceptable as long as you are willing to work | |
502 | toward a solution that is right. | |
503 | ||
504 | It is normal that the answers to your first patch might simply be a list | |
505 | of a dozen things you should correct. This does _not_ imply that your | |
506 | patch will not be accepted, and it is _not_ meant against you | |
507 | personally. Simply correct all issues raised against your patch and | |
508 | resend it. | |
509 | ||
510 | ||
511 | Differences between the kernel community and corporate structures | |
512 | ----------------------------------------------------------------- | |
513 | ||
514 | The kernel community works differently than most traditional corporate | |
515 | development environments. Here are a list of things that you can try to | |
516 | do to try to avoid problems: | |
517 | Good things to say regarding your proposed changes: | |
518 | - "This solves multiple problems." | |
519 | - "This deletes 2000 lines of code." | |
520 | - "Here is a patch that explains what I am trying to describe." | |
521 | - "I tested it on 5 different architectures..." | |
522 | - "Here is a series of small patches that..." | |
523 | - "This increases performance on typical machines..." | |
524 | ||
525 | Bad things you should avoid saying: | |
526 | - "We did it this way in AIX/ptx/Solaris, so therefore it must be | |
527 | good..." | |
528 | - "I've being doing this for 20 years, so..." | |
529 | - "This is required for my company to make money" | |
530 | - "This is for our Enterprise product line." | |
531 | - "Here is my 1000 page design document that describes my idea" | |
532 | - "I've been working on this for 6 months..." | |
533 | - "Here's a 5000 line patch that..." | |
534 | - "I rewrote all of the current mess, and here it is..." | |
535 | - "I have a deadline, and this patch needs to be applied now." | |
536 | ||
537 | Another way the kernel community is different than most traditional | |
538 | software engineering work environments is the faceless nature of | |
539 | interaction. One benefit of using email and irc as the primary forms of | |
540 | communication is the lack of discrimination based on gender or race. | |
541 | The Linux kernel work environment is accepting of women and minorities | |
542 | because all you are is an email address. The international aspect also | |
543 | helps to level the playing field because you can't guess gender based on | |
544 | a person's name. A man may be named Andrea and a woman may be named Pat. | |
545 | Most women who have worked in the Linux kernel and have expressed an | |
546 | opinion have had positive experiences. | |
547 | ||
548 | The language barrier can cause problems for some people who are not | |
549 | comfortable with English. A good grasp of the language can be needed in | |
550 | order to get ideas across properly on mailing lists, so it is | |
551 | recommended that you check your emails to make sure they make sense in | |
552 | English before sending them. | |
553 | ||
554 | ||
555 | Break up your changes | |
556 | --------------------- | |
557 | ||
558 | The Linux kernel community does not gladly accept large chunks of code | |
559 | dropped on it all at once. The changes need to be properly introduced, | |
560 | discussed, and broken up into tiny, individual portions. This is almost | |
561 | the exact opposite of what companies are used to doing. Your proposal | |
562 | should also be introduced very early in the development process, so that | |
563 | you can receive feedback on what you are doing. It also lets the | |
564 | community feel that you are working with them, and not simply using them | |
565 | as a dumping ground for your feature. However, don't send 50 emails at | |
566 | one time to a mailing list, your patch series should be smaller than | |
567 | that almost all of the time. | |
568 | ||
569 | The reasons for breaking things up are the following: | |
570 | ||
571 | 1) Small patches increase the likelihood that your patches will be | |
572 | applied, since they don't take much time or effort to verify for | |
573 | correctness. A 5 line patch can be applied by a maintainer with | |
574 | barely a second glance. However, a 500 line patch may take hours to | |
575 | review for correctness (the time it takes is exponentially | |
576 | proportional to the size of the patch, or something). | |
577 | ||
578 | Small patches also make it very easy to debug when something goes | |
579 | wrong. It's much easier to back out patches one by one than it is | |
580 | to dissect a very large patch after it's been applied (and broken | |
581 | something). | |
582 | ||
583 | 2) It's important not only to send small patches, but also to rewrite | |
584 | and simplify (or simply re-order) patches before submitting them. | |
585 | ||
586 | Here is an analogy from kernel developer Al Viro: | |
587 | "Think of a teacher grading homework from a math student. The | |
588 | teacher does not want to see the student's trials and errors | |
589 | before they came up with the solution. They want to see the | |
590 | cleanest, most elegant answer. A good student knows this, and | |
591 | would never submit her intermediate work before the final | |
592 | solution." | |
593 | ||
594 | The same is true of kernel development. The maintainers and | |
595 | reviewers do not want to see the thought process behind the | |
596 | solution to the problem one is solving. They want to see a | |
597 | simple and elegant solution." | |
598 | ||
599 | It may be challenging to keep the balance between presenting an elegant | |
600 | solution and working together with the community and discussing your | |
601 | unfinished work. Therefore it is good to get early in the process to | |
602 | get feedback to improve your work, but also keep your changes in small | |
603 | chunks that they may get already accepted, even when your whole task is | |
604 | not ready for inclusion now. | |
605 | ||
606 | Also realize that it is not acceptable to send patches for inclusion | |
607 | that are unfinished and will be "fixed up later." | |
608 | ||
609 | ||
610 | Justify your change | |
611 | ------------------- | |
612 | ||
613 | Along with breaking up your patches, it is very important for you to let | |
614 | the Linux community know why they should add this change. New features | |
615 | must be justified as being needed and useful. | |
616 | ||
617 | ||
618 | Document your change | |
619 | -------------------- | |
620 | ||
621 | When sending in your patches, pay special attention to what you say in | |
622 | the text in your email. This information will become the ChangeLog | |
623 | information for the patch, and will be preserved for everyone to see for | |
624 | all time. It should describe the patch completely, containing: | |
625 | - why the change is necessary | |
626 | - the overall design approach in the patch | |
627 | - implementation details | |
628 | - testing results | |
629 | ||
630 | For more details on what this should all look like, please see the | |
631 | ChangeLog section of the document: | |
632 | "The Perfect Patch" | |
633 | http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt | |
634 | ||
635 | ||
636 | ||
637 | ||
638 | All of these things are sometimes very hard to do. It can take years to | |
639 | perfect these practices (if at all). It's a continuous process of | |
640 | improvement that requires a lot of patience and determination. But | |
641 | don't give up, it's possible. Many have done it before, and each had to | |
642 | start exactly where you are now. | |
643 | ||
644 | ||
645 | ||
646 | ||
647 | ---------- | |
5bd982ed PC |
648 | Thanks to Paolo Ciarrocchi who allowed the "Development Process" |
649 | (http://linux.tar.bz/articles/2.6-development_process) section | |
d36cc9d0 GKH |
650 | to be based on text he had written, and to Randy Dunlap and Gerrit |
651 | Huizenga for some of the list of things you should and should not say. | |
652 | Also thanks to Pat Mochel, Hanna Linder, Randy Dunlap, Kay Sievers, | |
653 | Vojtech Pavlik, Jan Kara, Josh Boyer, Kees Cook, Andrew Morton, Andi | |
654 | Kleen, Vadim Lobanov, Jesper Juhl, Adrian Bunk, Keri Harris, Frans Pop, | |
655 | David A. Wheeler, Junio Hamano, Michael Kerrisk, and Alex Shepard for | |
656 | their review, comments, and contributions. Without their help, this | |
657 | document would not have been possible. | |
658 | ||
659 | ||
660 | ||
661 | Maintainer: Greg Kroah-Hartman <greg@kroah.com> |