Based on kernel version 4.8. Page generated on 2016-10-06 23:10 EST.
1 1: A GUIDE TO THE KERNEL DEVELOPMENT PROCESS 2 3 The purpose of this document is to help developers (and their managers) 4 work with the development community with a minimum of frustration. It is 5 an attempt to document how this community works in a way which is 6 accessible to those who are not intimately familiar with Linux kernel 7 development (or, indeed, free software development in general). While 8 there is some technical material here, this is very much a process-oriented 9 discussion which does not require a deep knowledge of kernel programming to 10 understand. 11 12 13 1.1: EXECUTIVE SUMMARY 14 15 The rest of this section covers the scope of the kernel development process 16 and the kinds of frustrations that developers and their employers can 17 encounter there. There are a great many reasons why kernel code should be 18 merged into the official ("mainline") kernel, including automatic 19 availability to users, community support in many forms, and the ability to 20 influence the direction of kernel development. Code contributed to the 21 Linux kernel must be made available under a GPL-compatible license. 22 23 Section 2 introduces the development process, the kernel release cycle, and 24 the mechanics of the merge window. The various phases in the patch 25 development, review, and merging cycle are covered. There is some 26 discussion of tools and mailing lists. Developers wanting to get started 27 with kernel development are encouraged to track down and fix bugs as an 28 initial exercise. 29 30 Section 3 covers early-stage project planning, with an emphasis on 31 involving the development community as soon as possible. 32 33 Section 4 is about the coding process; several pitfalls which have been 34 encountered by other developers are discussed. Some requirements for 35 patches are covered, and there is an introduction to some of the tools 36 which can help to ensure that kernel patches are correct. 37 38 Section 5 talks about the process of posting patches for review. To be 39 taken seriously by the development community, patches must be properly 40 formatted and described, and they must be sent to the right place. 41 Following the advice in this section should help to ensure the best 42 possible reception for your work. 43 44 Section 6 covers what happens after posting patches; the job is far from 45 done at that point. Working with reviewers is a crucial part of the 46 development process; this section offers a number of tips on how to avoid 47 problems at this important stage. Developers are cautioned against 48 assuming that the job is done when a patch is merged into the mainline. 49 50 Section 7 introduces a couple of "advanced" topics: managing patches with 51 git and reviewing patches posted by others. 52 53 Section 8 concludes the document with pointers to sources for more 54 information on kernel development. 55 56 57 1.2: WHAT THIS DOCUMENT IS ABOUT 58 59 The Linux kernel, at over 8 million lines of code and well over 1000 60 contributors to each release, is one of the largest and most active free 61 software projects in existence. Since its humble beginning in 1991, this 62 kernel has evolved into a best-of-breed operating system component which 63 runs on pocket-sized digital music players, desktop PCs, the largest 64 supercomputers in existence, and all types of systems in between. It is a 65 robust, efficient, and scalable solution for almost any situation. 66 67 With the growth of Linux has come an increase in the number of developers 68 (and companies) wishing to participate in its development. Hardware 69 vendors want to ensure that Linux supports their products well, making 70 those products attractive to Linux users. Embedded systems vendors, who 71 use Linux as a component in an integrated product, want Linux to be as 72 capable and well-suited to the task at hand as possible. Distributors and 73 other software vendors who base their products on Linux have a clear 74 interest in the capabilities, performance, and reliability of the Linux 75 kernel. And end users, too, will often wish to change Linux to make it 76 better suit their needs. 77 78 One of the most compelling features of Linux is that it is accessible to 79 these developers; anybody with the requisite skills can improve Linux and 80 influence the direction of its development. Proprietary products cannot 81 offer this kind of openness, which is a characteristic of the free software 82 process. But, if anything, the kernel is even more open than most other 83 free software projects. A typical three-month kernel development cycle can 84 involve over 1000 developers working for more than 100 different companies 85 (or for no company at all). 86 87 Working with the kernel development community is not especially hard. But, 88 that notwithstanding, many potential contributors have experienced 89 difficulties when trying to do kernel work. The kernel community has 90 evolved its own distinct ways of operating which allow it to function 91 smoothly (and produce a high-quality product) in an environment where 92 thousands of lines of code are being changed every day. So it is not 93 surprising that Linux kernel development process differs greatly from 94 proprietary development methods. 95 96 The kernel's development process may come across as strange and 97 intimidating to new developers, but there are good reasons and solid 98 experience behind it. A developer who does not understand the kernel 99 community's ways (or, worse, who tries to flout or circumvent them) will 100 have a frustrating experience in store. The development community, while 101 being helpful to those who are trying to learn, has little time for those 102 who will not listen or who do not care about the development process. 103 104 It is hoped that those who read this document will be able to avoid that 105 frustrating experience. There is a lot of material here, but the effort 106 involved in reading it will be repaid in short order. The development 107 community is always in need of developers who will help to make the kernel 108 better; the following text should help you - or those who work for you - 109 join our community. 110 111 112 1.3: CREDITS 113 114 This document was written by Jonathan Corbet, firstname.lastname@example.org. It has been 115 improved by comments from Johannes Berg, James Berry, Alex Chiang, Roland 116 Dreier, Randy Dunlap, Jake Edge, Jiri Kosina, Matt Mackall, Arthur Marsh, 117 Amanda McPherson, Andrew Morton, Andrew Price, Tsugikazu Shibata, and 118 Jochen Voß. 119 120 This work was supported by the Linux Foundation; thanks especially to 121 Amanda McPherson, who saw the value of this effort and made it all happen. 122 123 124 1.4: THE IMPORTANCE OF GETTING CODE INTO THE MAINLINE 125 126 Some companies and developers occasionally wonder why they should bother 127 learning how to work with the kernel community and get their code into the 128 mainline kernel (the "mainline" being the kernel maintained by Linus 129 Torvalds and used as a base by Linux distributors). In the short term, 130 contributing code can look like an avoidable expense; it seems easier to 131 just keep the code separate and support users directly. The truth of the 132 matter is that keeping code separate ("out of tree") is a false economy. 133 134 As a way of illustrating the costs of out-of-tree code, here are a few 135 relevant aspects of the kernel development process; most of these will be 136 discussed in greater detail later in this document. Consider: 137 138 - Code which has been merged into the mainline kernel is available to all 139 Linux users. It will automatically be present on all distributions which 140 enable it. There is no need for driver disks, downloads, or the hassles 141 of supporting multiple versions of multiple distributions; it all just 142 works, for the developer and for the user. Incorporation into the 143 mainline solves a large number of distribution and support problems. 144 145 - While kernel developers strive to maintain a stable interface to user 146 space, the internal kernel API is in constant flux. The lack of a stable 147 internal interface is a deliberate design decision; it allows fundamental 148 improvements to be made at any time and results in higher-quality code. 149 But one result of that policy is that any out-of-tree code requires 150 constant upkeep if it is to work with new kernels. Maintaining 151 out-of-tree code requires significant amounts of work just to keep that 152 code working. 153 154 Code which is in the mainline, instead, does not require this work as the 155 result of a simple rule requiring any developer who makes an API change 156 to also fix any code that breaks as the result of that change. So code 157 which has been merged into the mainline has significantly lower 158 maintenance costs. 159 160 - Beyond that, code which is in the kernel will often be improved by other 161 developers. Surprising results can come from empowering your user 162 community and customers to improve your product. 163 164 - Kernel code is subjected to review, both before and after merging into 165 the mainline. No matter how strong the original developer's skills are, 166 this review process invariably finds ways in which the code can be 167 improved. Often review finds severe bugs and security problems. This is 168 especially true for code which has been developed in a closed 169 environment; such code benefits strongly from review by outside 170 developers. Out-of-tree code is lower-quality code. 171 172 - Participation in the development process is your way to influence the 173 direction of kernel development. Users who complain from the sidelines 174 are heard, but active developers have a stronger voice - and the ability 175 to implement changes which make the kernel work better for their needs. 176 177 - When code is maintained separately, the possibility that a third party 178 will contribute a different implementation of a similar feature always 179 exists. Should that happen, getting your code merged will become much 180 harder - to the point of impossibility. Then you will be faced with the 181 unpleasant alternatives of either (1) maintaining a nonstandard feature 182 out of tree indefinitely, or (2) abandoning your code and migrating your 183 users over to the in-tree version. 184 185 - Contribution of code is the fundamental action which makes the whole 186 process work. By contributing your code you can add new functionality to 187 the kernel and provide capabilities and examples which are of use to 188 other kernel developers. If you have developed code for Linux (or are 189 thinking about doing so), you clearly have an interest in the continued 190 success of this platform; contributing code is one of the best ways to 191 help ensure that success. 192 193 All of the reasoning above applies to any out-of-tree kernel code, 194 including code which is distributed in proprietary, binary-only form. 195 There are, however, additional factors which should be taken into account 196 before considering any sort of binary-only kernel code distribution. These 197 include: 198 199 - The legal issues around the distribution of proprietary kernel modules 200 are cloudy at best; quite a few kernel copyright holders believe that 201 most binary-only modules are derived products of the kernel and that, as 202 a result, their distribution is a violation of the GNU General Public 203 license (about which more will be said below). Your author is not a 204 lawyer, and nothing in this document can possibly be considered to be 205 legal advice. The true legal status of closed-source modules can only be 206 determined by the courts. But the uncertainty which haunts those modules 207 is there regardless. 208 209 - Binary modules greatly increase the difficulty of debugging kernel 210 problems, to the point that most kernel developers will not even try. So 211 the distribution of binary-only modules will make it harder for your 212 users to get support from the community. 213 214 - Support is also harder for distributors of binary-only modules, who must 215 provide a version of the module for every distribution and every kernel 216 version they wish to support. Dozens of builds of a single module can 217 be required to provide reasonably comprehensive coverage, and your users 218 will have to upgrade your module separately every time they upgrade their 219 kernel. 220 221 - Everything that was said above about code review applies doubly to 222 closed-source code. Since this code is not available at all, it cannot 223 have been reviewed by the community and will, beyond doubt, have serious 224 problems. 225 226 Makers of embedded systems, in particular, may be tempted to disregard much 227 of what has been said in this section in the belief that they are shipping 228 a self-contained product which uses a frozen kernel version and requires no 229 more development after its release. This argument misses the value of 230 widespread code review and the value of allowing your users to add 231 capabilities to your product. But these products, too, have a limited 232 commercial life, after which a new version must be released. At that 233 point, vendors whose code is in the mainline and well maintained will be 234 much better positioned to get the new product ready for market quickly. 235 236 237 1.5: LICENSING 238 239 Code is contributed to the Linux kernel under a number of licenses, but all 240 code must be compatible with version 2 of the GNU General Public License 241 (GPLv2), which is the license covering the kernel distribution as a whole. 242 In practice, that means that all code contributions are covered either by 243 GPLv2 (with, optionally, language allowing distribution under later 244 versions of the GPL) or the three-clause BSD license. Any contributions 245 which are not covered by a compatible license will not be accepted into the 246 kernel. 247 248 Copyright assignments are not required (or requested) for code contributed 249 to the kernel. All code merged into the mainline kernel retains its 250 original ownership; as a result, the kernel now has thousands of owners. 251 252 One implication of this ownership structure is that any attempt to change 253 the licensing of the kernel is doomed to almost certain failure. There are 254 few practical scenarios where the agreement of all copyright holders could 255 be obtained (or their code removed from the kernel). So, in particular, 256 there is no prospect of a migration to version 3 of the GPL in the 257 foreseeable future. 258 259 It is imperative that all code contributed to the kernel be legitimately 260 free software. For that reason, code from anonymous (or pseudonymous) 261 contributors will not be accepted. All contributors are required to "sign 262 off" on their code, stating that the code can be distributed with the 263 kernel under the GPL. Code which has not been licensed as free software by 264 its owner, or which risks creating copyright-related problems for the 265 kernel (such as code which derives from reverse-engineering efforts lacking 266 proper safeguards) cannot be contributed. 267 268 Questions about copyright-related issues are common on Linux development 269 mailing lists. Such questions will normally receive no shortage of 270 answers, but one should bear in mind that the people answering those 271 questions are not lawyers and cannot provide legal advice. If you have 272 legal questions relating to Linux source code, there is no substitute for 273 talking with a lawyer who understands this field. Relying on answers 274 obtained on technical mailing lists is a risky affair.