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