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