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