Greg Kroah-Hartman | d36cc9d | 2005-11-18 09:31:11 -0800 | [diff] [blame] | 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] |
Robert P. J. Day | 4de0ca8 | 2007-01-17 04:54:07 -0500 | [diff] [blame] | 33 | - "C: A Reference Manual" by Harbison and Steele [Prentice Hall] |
Greg Kroah-Hartman | d36cc9d | 2005-11-18 09:31:11 -0800 | [diff] [blame] | 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 |
Michael Kerrisk | 09b05f5 | 2008-10-03 15:23:45 -0700 | [diff] [blame] | 80 | maintainer at mtk.manpages@gmail.com, and CC the list |
| 81 | linux-api@vger.kernel.org. |
Greg Kroah-Hartman | d36cc9d | 2005-11-18 09:31:11 -0800 | [diff] [blame] | 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" |
SeongJae Park | 937d9f5 | 2013-12-06 18:04:42 +0900 | [diff] [blame] | 115 | http://www.ozlabs.org/~akpm/stuff/tpp.txt |
Greg Kroah-Hartman | d36cc9d | 2005-11-18 09:31:11 -0800 | [diff] [blame] | 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: |
Peter Loeffler | 5645a71 | 2016-01-30 21:53:53 +0100 | [diff] [blame] | 190 | http://kernelnewbies.org/KernelJanitors |
Greg Kroah-Hartman | d36cc9d | 2005-11-18 09:31:11 -0800 | [diff] [blame] | 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: |
Doug Smythies | 1d12554 | 2015-11-22 15:42:48 -0800 | [diff] [blame] | 212 | http://lxr.free-electrons.com/ |
Greg Kroah-Hartman | d36cc9d | 2005-11-18 09:31:11 -0800 | [diff] [blame] | 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: |
Mario Carrillo | e4144fe | 2015-08-24 09:33:09 -0500 | [diff] [blame] | 221 | - main 4.x kernel tree |
| 222 | - 4.x.y -stable kernel tree |
| 223 | - 4.x -git kernel patches |
Greg Kroah-Hartman | d36cc9d | 2005-11-18 09:31:11 -0800 | [diff] [blame] | 224 | - subsystem specific kernel trees and patches |
Mario Carrillo | e4144fe | 2015-08-24 09:33:09 -0500 | [diff] [blame] | 225 | - the 4.x -next kernel tree for integration tests |
Greg Kroah-Hartman | d36cc9d | 2005-11-18 09:31:11 -0800 | [diff] [blame] | 226 | |
Mario Carrillo | e4144fe | 2015-08-24 09:33:09 -0500 | [diff] [blame] | 227 | 4.x kernel tree |
Greg Kroah-Hartman | d36cc9d | 2005-11-18 09:31:11 -0800 | [diff] [blame] | 228 | ----------------- |
Mario Carrillo | e4144fe | 2015-08-24 09:33:09 -0500 | [diff] [blame] | 229 | 4.x kernels are maintained by Linus Torvalds, and can be found on |
| 230 | kernel.org in the pub/linux/kernel/v4.x/ directory. Its development |
Greg Kroah-Hartman | d36cc9d | 2005-11-18 09:31:11 -0800 | [diff] [blame] | 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 |
Stefan Richter | c607cf0 | 2010-01-15 13:23:51 +0100 | [diff] [blame] | 235 | -next kernel for a few weeks. The preferred way to submit big changes |
Greg Kroah-Hartman | d36cc9d | 2005-11-18 09:31:11 -0800 | [diff] [blame] | 236 | is using git (the kernel's source management tool, more information |
Randy Dunlap | e234ebf | 2010-04-06 16:16:59 -0700 | [diff] [blame] | 237 | can be found at http://git-scm.com/) but plain patches are also just |
Greg Kroah-Hartman | d36cc9d | 2005-11-18 09:31:11 -0800 | [diff] [blame] | 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 | |
| 254 | It is worth mentioning what Andrew Morton wrote on the linux-kernel |
| 255 | mailing list about kernel releases: |
| 256 | "Nobody knows when a kernel will be released, because it's |
| 257 | released according to perceived bug status, not according to a |
| 258 | preconceived timeline." |
| 259 | |
Mario Carrillo | e4144fe | 2015-08-24 09:33:09 -0500 | [diff] [blame] | 260 | 4.x.y -stable kernel tree |
Greg Kroah-Hartman | d36cc9d | 2005-11-18 09:31:11 -0800 | [diff] [blame] | 261 | --------------------------- |
Kees Cook | 591bfc6 | 2012-04-18 23:16:45 -0700 | [diff] [blame] | 262 | Kernels with 3-part versions are -stable kernels. They contain |
Greg Kroah-Hartman | d36cc9d | 2005-11-18 09:31:11 -0800 | [diff] [blame] | 263 | relatively small and critical fixes for security problems or significant |
Mario Carrillo | e4144fe | 2015-08-24 09:33:09 -0500 | [diff] [blame] | 264 | regressions discovered in a given 4.x kernel. |
Greg Kroah-Hartman | d36cc9d | 2005-11-18 09:31:11 -0800 | [diff] [blame] | 265 | |
| 266 | This is the recommended branch for users who want the most recent stable |
| 267 | kernel and are not interested in helping test development/experimental |
| 268 | versions. |
| 269 | |
Mario Carrillo | e4144fe | 2015-08-24 09:33:09 -0500 | [diff] [blame] | 270 | If no 4.x.y kernel is available, then the highest numbered 4.x |
Greg Kroah-Hartman | d36cc9d | 2005-11-18 09:31:11 -0800 | [diff] [blame] | 271 | kernel is the current stable kernel. |
| 272 | |
Mario Carrillo | e4144fe | 2015-08-24 09:33:09 -0500 | [diff] [blame] | 273 | 4.x.y are maintained by the "stable" team <stable@vger.kernel.org>, and |
Joe Perches | 2eb7f20 | 2011-12-09 14:12:00 -0800 | [diff] [blame] | 274 | are released as needs dictate. The normal release period is approximately |
Jonathan Corbet | 0fe8a3c | 2008-04-25 11:23:56 -0600 | [diff] [blame] | 275 | two weeks, but it can be longer if there are no pressing problems. A |
| 276 | security-related problem, instead, can cause a release to happen almost |
| 277 | instantly. |
Greg Kroah-Hartman | d36cc9d | 2005-11-18 09:31:11 -0800 | [diff] [blame] | 278 | |
| 279 | The file Documentation/stable_kernel_rules.txt in the kernel tree |
| 280 | documents what kinds of changes are acceptable for the -stable tree, and |
| 281 | how the release process works. |
| 282 | |
Mario Carrillo | e4144fe | 2015-08-24 09:33:09 -0500 | [diff] [blame] | 283 | 4.x -git patches |
Greg Kroah-Hartman | d36cc9d | 2005-11-18 09:31:11 -0800 | [diff] [blame] | 284 | ------------------ |
| 285 | These are daily snapshots of Linus' kernel tree which are managed in a |
| 286 | git repository (hence the name.) These patches are usually released |
| 287 | daily and represent the current state of Linus' tree. They are more |
| 288 | experimental than -rc kernels since they are generated automatically |
| 289 | without even a cursory glance to see if they are sane. |
| 290 | |
Greg Kroah-Hartman | d36cc9d | 2005-11-18 09:31:11 -0800 | [diff] [blame] | 291 | Subsystem Specific kernel trees and patches |
| 292 | ------------------------------------------- |
Stefan Richter | c607cf0 | 2010-01-15 13:23:51 +0100 | [diff] [blame] | 293 | The maintainers of the various kernel subsystems --- and also many |
| 294 | kernel subsystem developers --- expose their current state of |
| 295 | development in source repositories. That way, others can see what is |
| 296 | happening in the different areas of the kernel. In areas where |
| 297 | development is rapid, a developer may be asked to base his submissions |
| 298 | onto such a subsystem kernel tree so that conflicts between the |
| 299 | submission and other already ongoing work are avoided. |
Greg Kroah-Hartman | d36cc9d | 2005-11-18 09:31:11 -0800 | [diff] [blame] | 300 | |
Stefan Richter | c607cf0 | 2010-01-15 13:23:51 +0100 | [diff] [blame] | 301 | Most of these repositories are git trees, but there are also other SCMs |
| 302 | in use, or patch queues being published as quilt series. Addresses of |
| 303 | these subsystem repositories are listed in the MAINTAINERS file. Many |
| 304 | of them can be browsed at http://git.kernel.org/. |
Greg Kroah-Hartman | d36cc9d | 2005-11-18 09:31:11 -0800 | [diff] [blame] | 305 | |
Stefan Richter | c607cf0 | 2010-01-15 13:23:51 +0100 | [diff] [blame] | 306 | Before a proposed patch is committed to such a subsystem tree, it is |
| 307 | subject to review which primarily happens on mailing lists (see the |
| 308 | respective section below). For several kernel subsystems, this review |
| 309 | process is tracked with the tool patchwork. Patchwork offers a web |
| 310 | interface which shows patch postings, any comments on a patch or |
| 311 | revisions to it, and maintainers can mark patches as under review, |
| 312 | accepted, or rejected. Most of these patchwork sites are listed at |
Justin P. Mattock | 0ea6e61 | 2010-07-23 20:51:24 -0700 | [diff] [blame] | 313 | http://patchwork.kernel.org/. |
Greg Kroah-Hartman | d36cc9d | 2005-11-18 09:31:11 -0800 | [diff] [blame] | 314 | |
Mario Carrillo | e4144fe | 2015-08-24 09:33:09 -0500 | [diff] [blame] | 315 | 4.x -next kernel tree for integration tests |
Stefan Richter | c607cf0 | 2010-01-15 13:23:51 +0100 | [diff] [blame] | 316 | --------------------------------------------- |
Mario Carrillo | e4144fe | 2015-08-24 09:33:09 -0500 | [diff] [blame] | 317 | Before updates from subsystem trees are merged into the mainline 4.x |
Stefan Richter | c607cf0 | 2010-01-15 13:23:51 +0100 | [diff] [blame] | 318 | tree, they need to be integration-tested. For this purpose, a special |
| 319 | testing repository exists into which virtually all subsystem trees are |
| 320 | pulled on an almost daily basis: |
Kees Cook | 591bfc6 | 2012-04-18 23:16:45 -0700 | [diff] [blame] | 321 | http://git.kernel.org/?p=linux/kernel/git/next/linux-next.git |
Greg Kroah-Hartman | d36cc9d | 2005-11-18 09:31:11 -0800 | [diff] [blame] | 322 | |
Stefan Richter | c607cf0 | 2010-01-15 13:23:51 +0100 | [diff] [blame] | 323 | This way, the -next kernel gives a summary outlook onto what will be |
| 324 | expected to go into the mainline kernel at the next merge period. |
| 325 | Adventurous testers are very welcome to runtime-test the -next kernel. |
Greg Kroah-Hartman | d36cc9d | 2005-11-18 09:31:11 -0800 | [diff] [blame] | 326 | |
Stefan Richter | 8a465c3 | 2007-06-27 14:10:01 -0700 | [diff] [blame] | 327 | |
Greg Kroah-Hartman | d36cc9d | 2005-11-18 09:31:11 -0800 | [diff] [blame] | 328 | Bug Reporting |
| 329 | ------------- |
| 330 | |
| 331 | bugzilla.kernel.org is where the Linux kernel developers track kernel |
| 332 | bugs. Users are encouraged to report all bugs that they find in this |
| 333 | tool. For details on how to use the kernel bugzilla, please see: |
Jiri Pirko | 0302c01 | 2008-07-13 12:13:59 -0700 | [diff] [blame] | 334 | http://bugzilla.kernel.org/page.cgi?id=faq.html |
Greg Kroah-Hartman | d36cc9d | 2005-11-18 09:31:11 -0800 | [diff] [blame] | 335 | |
| 336 | The file REPORTING-BUGS in the main kernel source directory has a good |
| 337 | template for how to report a possible kernel bug, and details what kind |
| 338 | of information is needed by the kernel developers to help track down the |
| 339 | problem. |
| 340 | |
| 341 | |
Diego Calleja | 3f27100 | 2006-09-30 23:27:49 -0700 | [diff] [blame] | 342 | Managing bug reports |
| 343 | -------------------- |
| 344 | |
| 345 | One of the best ways to put into practice your hacking skills is by fixing |
| 346 | bugs reported by other people. Not only you will help to make the kernel |
| 347 | more stable, you'll learn to fix real world problems and you will improve |
| 348 | your skills, and other developers will be aware of your presence. Fixing |
Qi Yong | 4db29c1 | 2007-06-12 13:06:49 +0800 | [diff] [blame] | 349 | bugs is one of the best ways to get merits among other developers, because |
Diego Calleja | 3f27100 | 2006-09-30 23:27:49 -0700 | [diff] [blame] | 350 | not many people like wasting time fixing other people's bugs. |
| 351 | |
| 352 | To work in the already reported bug reports, go to http://bugzilla.kernel.org. |
| 353 | If you want to be advised of the future bug reports, you can subscribe to the |
| 354 | bugme-new mailing list (only new bug reports are mailed here) or to the |
| 355 | bugme-janitor mailing list (every change in the bugzilla is mailed here) |
| 356 | |
Jonathan Corbet | 0fe8a3c | 2008-04-25 11:23:56 -0600 | [diff] [blame] | 357 | http://lists.linux-foundation.org/mailman/listinfo/bugme-new |
| 358 | http://lists.linux-foundation.org/mailman/listinfo/bugme-janitors |
Diego Calleja | 3f27100 | 2006-09-30 23:27:49 -0700 | [diff] [blame] | 359 | |
| 360 | |
| 361 | |
Greg Kroah-Hartman | d36cc9d | 2005-11-18 09:31:11 -0800 | [diff] [blame] | 362 | Mailing lists |
| 363 | ------------- |
| 364 | |
| 365 | As some of the above documents describe, the majority of the core kernel |
| 366 | developers participate on the Linux Kernel Mailing list. Details on how |
| 367 | to subscribe and unsubscribe from the list can be found at: |
| 368 | http://vger.kernel.org/vger-lists.html#linux-kernel |
| 369 | There are archives of the mailing list on the web in many different |
| 370 | places. Use a search engine to find these archives. For example: |
| 371 | http://dir.gmane.org/gmane.linux.kernel |
| 372 | It is highly recommended that you search the archives about the topic |
| 373 | you want to bring up, before you post it to the list. A lot of things |
| 374 | already discussed in detail are only recorded at the mailing list |
| 375 | archives. |
| 376 | |
| 377 | Most of the individual kernel subsystems also have their own separate |
| 378 | mailing list where they do their development efforts. See the |
| 379 | MAINTAINERS file for a list of what these lists are for the different |
| 380 | groups. |
| 381 | |
| 382 | Many of the lists are hosted on kernel.org. Information on them can be |
| 383 | found at: |
| 384 | http://vger.kernel.org/vger-lists.html |
| 385 | |
| 386 | Please remember to follow good behavioral habits when using the lists. |
| 387 | Though a bit cheesy, the following URL has some simple guidelines for |
| 388 | interacting with the list (or any list): |
| 389 | http://www.albion.com/netiquette/ |
| 390 | |
| 391 | If multiple people respond to your mail, the CC: list of recipients may |
| 392 | get pretty large. Don't remove anybody from the CC: list without a good |
| 393 | reason, or don't reply only to the list address. Get used to receiving the |
| 394 | mail twice, one from the sender and the one from the list, and don't try |
| 395 | to tune that by adding fancy mail-headers, people will not like it. |
| 396 | |
| 397 | Remember to keep the context and the attribution of your replies intact, |
| 398 | keep the "John Kernelhacker wrote ...:" lines at the top of your reply, and |
| 399 | add your statements between the individual quoted sections instead of |
| 400 | writing at the top of the mail. |
| 401 | |
| 402 | If you add patches to your mail, make sure they are plain readable text |
| 403 | as stated in Documentation/SubmittingPatches. Kernel developers don't |
| 404 | want to deal with attachments or compressed patches; they may want |
| 405 | to comment on individual lines of your patch, which works only that way. |
| 406 | Make sure you use a mail program that does not mangle spaces and tab |
| 407 | characters. A good first test is to send the mail to yourself and try |
| 408 | to apply your own patch by yourself. If that doesn't work, get your |
| 409 | mail program fixed or change it until it works. |
| 410 | |
| 411 | Above all, please remember to show respect to other subscribers. |
| 412 | |
| 413 | |
| 414 | Working with the community |
| 415 | -------------------------- |
| 416 | |
| 417 | The goal of the kernel community is to provide the best possible kernel |
| 418 | there is. When you submit a patch for acceptance, it will be reviewed |
| 419 | on its technical merits and those alone. So, what should you be |
| 420 | expecting? |
| 421 | - criticism |
| 422 | - comments |
| 423 | - requests for change |
| 424 | - requests for justification |
| 425 | - silence |
| 426 | |
| 427 | Remember, this is part of getting your patch into the kernel. You have |
| 428 | to be able to take criticism and comments about your patches, evaluate |
| 429 | them at a technical level and either rework your patches or provide |
| 430 | clear and concise reasoning as to why those changes should not be made. |
| 431 | If there are no responses to your posting, wait a few days and try |
| 432 | again, sometimes things get lost in the huge volume. |
| 433 | |
| 434 | What should you not do? |
| 435 | - expect your patch to be accepted without question |
| 436 | - become defensive |
| 437 | - ignore comments |
| 438 | - resubmit the patch without making any of the requested changes |
| 439 | |
| 440 | In a community that is looking for the best technical solution possible, |
| 441 | there will always be differing opinions on how beneficial a patch is. |
| 442 | You have to be cooperative, and willing to adapt your idea to fit within |
| 443 | the kernel. Or at least be willing to prove your idea is worth it. |
| 444 | Remember, being wrong is acceptable as long as you are willing to work |
| 445 | toward a solution that is right. |
| 446 | |
| 447 | It is normal that the answers to your first patch might simply be a list |
| 448 | of a dozen things you should correct. This does _not_ imply that your |
| 449 | patch will not be accepted, and it is _not_ meant against you |
| 450 | personally. Simply correct all issues raised against your patch and |
| 451 | resend it. |
| 452 | |
| 453 | |
| 454 | Differences between the kernel community and corporate structures |
| 455 | ----------------------------------------------------------------- |
| 456 | |
| 457 | The kernel community works differently than most traditional corporate |
| 458 | development environments. Here are a list of things that you can try to |
Cristian Stoica | 106f9d9 | 2012-12-07 16:37:11 +0200 | [diff] [blame] | 459 | do to avoid problems: |
Greg Kroah-Hartman | d36cc9d | 2005-11-18 09:31:11 -0800 | [diff] [blame] | 460 | Good things to say regarding your proposed changes: |
| 461 | - "This solves multiple problems." |
| 462 | - "This deletes 2000 lines of code." |
| 463 | - "Here is a patch that explains what I am trying to describe." |
| 464 | - "I tested it on 5 different architectures..." |
| 465 | - "Here is a series of small patches that..." |
| 466 | - "This increases performance on typical machines..." |
| 467 | |
| 468 | Bad things you should avoid saying: |
| 469 | - "We did it this way in AIX/ptx/Solaris, so therefore it must be |
| 470 | good..." |
| 471 | - "I've being doing this for 20 years, so..." |
| 472 | - "This is required for my company to make money" |
| 473 | - "This is for our Enterprise product line." |
| 474 | - "Here is my 1000 page design document that describes my idea" |
| 475 | - "I've been working on this for 6 months..." |
| 476 | - "Here's a 5000 line patch that..." |
| 477 | - "I rewrote all of the current mess, and here it is..." |
| 478 | - "I have a deadline, and this patch needs to be applied now." |
| 479 | |
| 480 | Another way the kernel community is different than most traditional |
| 481 | software engineering work environments is the faceless nature of |
| 482 | interaction. One benefit of using email and irc as the primary forms of |
| 483 | communication is the lack of discrimination based on gender or race. |
| 484 | The Linux kernel work environment is accepting of women and minorities |
| 485 | because all you are is an email address. The international aspect also |
| 486 | helps to level the playing field because you can't guess gender based on |
| 487 | a person's name. A man may be named Andrea and a woman may be named Pat. |
| 488 | Most women who have worked in the Linux kernel and have expressed an |
| 489 | opinion have had positive experiences. |
| 490 | |
| 491 | The language barrier can cause problems for some people who are not |
| 492 | comfortable with English. A good grasp of the language can be needed in |
| 493 | order to get ideas across properly on mailing lists, so it is |
| 494 | recommended that you check your emails to make sure they make sense in |
| 495 | English before sending them. |
| 496 | |
| 497 | |
| 498 | Break up your changes |
| 499 | --------------------- |
| 500 | |
| 501 | The Linux kernel community does not gladly accept large chunks of code |
| 502 | dropped on it all at once. The changes need to be properly introduced, |
| 503 | discussed, and broken up into tiny, individual portions. This is almost |
| 504 | the exact opposite of what companies are used to doing. Your proposal |
| 505 | should also be introduced very early in the development process, so that |
| 506 | you can receive feedback on what you are doing. It also lets the |
| 507 | community feel that you are working with them, and not simply using them |
| 508 | as a dumping ground for your feature. However, don't send 50 emails at |
| 509 | one time to a mailing list, your patch series should be smaller than |
| 510 | that almost all of the time. |
| 511 | |
| 512 | The reasons for breaking things up are the following: |
| 513 | |
| 514 | 1) Small patches increase the likelihood that your patches will be |
| 515 | applied, since they don't take much time or effort to verify for |
| 516 | correctness. A 5 line patch can be applied by a maintainer with |
| 517 | barely a second glance. However, a 500 line patch may take hours to |
| 518 | review for correctness (the time it takes is exponentially |
| 519 | proportional to the size of the patch, or something). |
| 520 | |
| 521 | Small patches also make it very easy to debug when something goes |
| 522 | wrong. It's much easier to back out patches one by one than it is |
| 523 | to dissect a very large patch after it's been applied (and broken |
| 524 | something). |
| 525 | |
| 526 | 2) It's important not only to send small patches, but also to rewrite |
| 527 | and simplify (or simply re-order) patches before submitting them. |
| 528 | |
| 529 | Here is an analogy from kernel developer Al Viro: |
| 530 | "Think of a teacher grading homework from a math student. The |
| 531 | teacher does not want to see the student's trials and errors |
| 532 | before they came up with the solution. They want to see the |
| 533 | cleanest, most elegant answer. A good student knows this, and |
| 534 | would never submit her intermediate work before the final |
| 535 | solution." |
| 536 | |
| 537 | The same is true of kernel development. The maintainers and |
| 538 | reviewers do not want to see the thought process behind the |
| 539 | solution to the problem one is solving. They want to see a |
| 540 | simple and elegant solution." |
| 541 | |
| 542 | It may be challenging to keep the balance between presenting an elegant |
| 543 | solution and working together with the community and discussing your |
| 544 | unfinished work. Therefore it is good to get early in the process to |
| 545 | get feedback to improve your work, but also keep your changes in small |
| 546 | chunks that they may get already accepted, even when your whole task is |
| 547 | not ready for inclusion now. |
| 548 | |
| 549 | Also realize that it is not acceptable to send patches for inclusion |
| 550 | that are unfinished and will be "fixed up later." |
| 551 | |
| 552 | |
| 553 | Justify your change |
| 554 | ------------------- |
| 555 | |
| 556 | Along with breaking up your patches, it is very important for you to let |
| 557 | the Linux community know why they should add this change. New features |
| 558 | must be justified as being needed and useful. |
| 559 | |
| 560 | |
| 561 | Document your change |
| 562 | -------------------- |
| 563 | |
| 564 | When sending in your patches, pay special attention to what you say in |
| 565 | the text in your email. This information will become the ChangeLog |
| 566 | information for the patch, and will be preserved for everyone to see for |
| 567 | all time. It should describe the patch completely, containing: |
| 568 | - why the change is necessary |
| 569 | - the overall design approach in the patch |
| 570 | - implementation details |
| 571 | - testing results |
| 572 | |
| 573 | For more details on what this should all look like, please see the |
| 574 | ChangeLog section of the document: |
| 575 | "The Perfect Patch" |
SeongJae Park | 937d9f5 | 2013-12-06 18:04:42 +0900 | [diff] [blame] | 576 | http://www.ozlabs.org/~akpm/stuff/tpp.txt |
Greg Kroah-Hartman | d36cc9d | 2005-11-18 09:31:11 -0800 | [diff] [blame] | 577 | |
| 578 | |
| 579 | |
| 580 | |
| 581 | All of these things are sometimes very hard to do. It can take years to |
| 582 | perfect these practices (if at all). It's a continuous process of |
| 583 | improvement that requires a lot of patience and determination. But |
| 584 | don't give up, it's possible. Many have done it before, and each had to |
| 585 | start exactly where you are now. |
| 586 | |
| 587 | |
| 588 | |
| 589 | |
| 590 | ---------- |
Paolo Ciarrocchi | 5bd982e | 2006-04-25 22:47:51 +0200 | [diff] [blame] | 591 | Thanks to Paolo Ciarrocchi who allowed the "Development Process" |
Justin P. Mattock | 0ea6e61 | 2010-07-23 20:51:24 -0700 | [diff] [blame] | 592 | (http://lwn.net/Articles/94386/) section |
Greg Kroah-Hartman | d36cc9d | 2005-11-18 09:31:11 -0800 | [diff] [blame] | 593 | to be based on text he had written, and to Randy Dunlap and Gerrit |
| 594 | Huizenga for some of the list of things you should and should not say. |
| 595 | Also thanks to Pat Mochel, Hanna Linder, Randy Dunlap, Kay Sievers, |
| 596 | Vojtech Pavlik, Jan Kara, Josh Boyer, Kees Cook, Andrew Morton, Andi |
| 597 | Kleen, Vadim Lobanov, Jesper Juhl, Adrian Bunk, Keri Harris, Frans Pop, |
| 598 | David A. Wheeler, Junio Hamano, Michael Kerrisk, and Alex Shepard for |
| 599 | their review, comments, and contributions. Without their help, this |
| 600 | document would not have been possible. |
| 601 | |
| 602 | |
| 603 | |
| 604 | Maintainer: Greg Kroah-Hartman <greg@kroah.com> |