269 lines · plain
1.. _development_process_intro:2 3Introduction4============5 6Executive summary7-----------------8 9The rest of this section covers the scope of the kernel development process10and the kinds of frustrations that developers and their employers can11encounter there. There are a great many reasons why kernel code should be12merged into the official ("mainline") kernel, including automatic13availability to users, community support in many forms, and the ability to14influence the direction of kernel development. Code contributed to the15Linux kernel must be made available under a GPL-compatible license.16 17:ref:`development_process` introduces the development process, the kernel18release cycle, and the mechanics of the merge window. The various phases in19the patch development, review, and merging cycle are covered. There is some20discussion of tools and mailing lists. Developers wanting to get started21with kernel development are encouraged to track down and fix bugs as an22initial exercise.23 24:ref:`development_early_stage` covers early-stage project planning, with an25emphasis on involving the development community as soon as possible.26 27:ref:`development_coding` is about the coding process; several pitfalls which28have been encountered by other developers are discussed. Some requirements for29patches are covered, and there is an introduction to some of the tools30which can help to ensure that kernel patches are correct.31 32:ref:`development_posting` talks about the process of posting patches for33review. To be taken seriously by the development community, patches must be34properly formatted and described, and they must be sent to the right place.35Following the advice in this section should help to ensure the best36possible reception for your work.37 38:ref:`development_followthrough` covers what happens after posting patches; the39job is far from done at that point. Working with reviewers is a crucial part40of the development process; this section offers a number of tips on how to41avoid problems at this important stage. Developers are cautioned against42assuming that the job is done when a patch is merged into the mainline.43 44:ref:`development_advancedtopics` introduces a couple of "advanced" topics:45managing patches with git and reviewing patches posted by others.46 47:ref:`development_conclusion` concludes the document with pointers to sources48for more information on kernel development.49 50What this document is about51---------------------------52 53The Linux kernel, at over 8 million lines of code and well over 100054contributors to each release, is one of the largest and most active free55software projects in existence. Since its humble beginning in 1991, this56kernel has evolved into a best-of-breed operating system component which57runs on pocket-sized digital music players, desktop PCs, the largest58supercomputers in existence, and all types of systems in between. It is a59robust, efficient, and scalable solution for almost any situation.60 61With the growth of Linux has come an increase in the number of developers62(and companies) wishing to participate in its development. Hardware63vendors want to ensure that Linux supports their products well, making64those products attractive to Linux users. Embedded systems vendors, who65use Linux as a component in an integrated product, want Linux to be as66capable and well-suited to the task at hand as possible. Distributors and67other software vendors who base their products on Linux have a clear68interest in the capabilities, performance, and reliability of the Linux69kernel. And end users, too, will often wish to change Linux to make it70better suit their needs.71 72One of the most compelling features of Linux is that it is accessible to73these developers; anybody with the requisite skills can improve Linux and74influence the direction of its development. Proprietary products cannot75offer this kind of openness, which is a characteristic of the free software76process. But, if anything, the kernel is even more open than most other77free software projects. A typical three-month kernel development cycle can78involve over 1000 developers working for more than 100 different companies79(or for no company at all).80 81Working with the kernel development community is not especially hard. But,82that notwithstanding, many potential contributors have experienced83difficulties when trying to do kernel work. The kernel community has84evolved its own distinct ways of operating which allow it to function85smoothly (and produce a high-quality product) in an environment where86thousands of lines of code are being changed every day. So it is not87surprising that Linux kernel development process differs greatly from88proprietary development methods.89 90The kernel's development process may come across as strange and91intimidating to new developers, but there are good reasons and solid92experience behind it. A developer who does not understand the kernel93community's ways (or, worse, who tries to flout or circumvent them) will94have a frustrating experience in store. The development community, while95being helpful to those who are trying to learn, has little time for those96who will not listen or who do not care about the development process.97 98It is hoped that those who read this document will be able to avoid that99frustrating experience. There is a lot of material here, but the effort100involved in reading it will be repaid in short order. The development101community is always in need of developers who will help to make the kernel102better; the following text should help you - or those who work for you -103join our community.104 105Credits106-------107 108This document was written by Jonathan Corbet, corbet@lwn.net. It has been109improved by comments from Johannes Berg, James Berry, Alex Chiang, Roland110Dreier, Randy Dunlap, Jake Edge, Jiri Kosina, Matt Mackall, Arthur Marsh,111Amanda McPherson, Andrew Morton, Andrew Price, Tsugikazu Shibata, and112Jochen Voß.113 114This work was supported by the Linux Foundation; thanks especially to115Amanda McPherson, who saw the value of this effort and made it all happen.116 117The importance of getting code into the mainline118------------------------------------------------119 120Some companies and developers occasionally wonder why they should bother121learning how to work with the kernel community and get their code into the122mainline kernel (the "mainline" being the kernel maintained by Linus123Torvalds and used as a base by Linux distributors). In the short term,124contributing code can look like an avoidable expense; it seems easier to125just keep the code separate and support users directly. The truth of the126matter is that keeping code separate ("out of tree") is a false economy.127 128As a way of illustrating the costs of out-of-tree code, here are a few129relevant aspects of the kernel development process; most of these will be130discussed in greater detail later in this document. Consider:131 132- Code which has been merged into the mainline kernel is available to all133 Linux users. It will automatically be present on all distributions which134 enable it. There is no need for driver disks, downloads, or the hassles135 of supporting multiple versions of multiple distributions; it all just136 works, for the developer and for the user. Incorporation into the137 mainline solves a large number of distribution and support problems.138 139- While kernel developers strive to maintain a stable interface to user140 space, the internal kernel API is in constant flux. The lack of a stable141 internal interface is a deliberate design decision; it allows fundamental142 improvements to be made at any time and results in higher-quality code.143 But one result of that policy is that any out-of-tree code requires144 constant upkeep if it is to work with new kernels. Maintaining145 out-of-tree code requires significant amounts of work just to keep that146 code working.147 148 Code which is in the mainline, instead, does not require this work as the149 result of a simple rule requiring any developer who makes an API change150 to also fix any code that breaks as the result of that change. So code151 which has been merged into the mainline has significantly lower152 maintenance costs.153 154- Beyond that, code which is in the kernel will often be improved by other155 developers. Surprising results can come from empowering your user156 community and customers to improve your product.157 158- Kernel code is subjected to review, both before and after merging into159 the mainline. No matter how strong the original developer's skills are,160 this review process invariably finds ways in which the code can be161 improved. Often review finds severe bugs and security problems. This is162 especially true for code which has been developed in a closed163 environment; such code benefits strongly from review by outside164 developers. Out-of-tree code is lower-quality code.165 166- Participation in the development process is your way to influence the167 direction of kernel development. Users who complain from the sidelines168 are heard, but active developers have a stronger voice - and the ability169 to implement changes which make the kernel work better for their needs.170 171- When code is maintained separately, the possibility that a third party172 will contribute a different implementation of a similar feature always173 exists. Should that happen, getting your code merged will become much174 harder - to the point of impossibility. Then you will be faced with the175 unpleasant alternatives of either (1) maintaining a nonstandard feature176 out of tree indefinitely, or (2) abandoning your code and migrating your177 users over to the in-tree version.178 179- Contribution of code is the fundamental action which makes the whole180 process work. By contributing your code you can add new functionality to181 the kernel and provide capabilities and examples which are of use to182 other kernel developers. If you have developed code for Linux (or are183 thinking about doing so), you clearly have an interest in the continued184 success of this platform; contributing code is one of the best ways to185 help ensure that success.186 187All of the reasoning above applies to any out-of-tree kernel code,188including code which is distributed in proprietary, binary-only form.189There are, however, additional factors which should be taken into account190before considering any sort of binary-only kernel code distribution. These191include:192 193- The legal issues around the distribution of proprietary kernel modules194 are cloudy at best; quite a few kernel copyright holders believe that195 most binary-only modules are derived products of the kernel and that, as196 a result, their distribution is a violation of the GNU General Public197 license (about which more will be said below). Your author is not a198 lawyer, and nothing in this document can possibly be considered to be199 legal advice. The true legal status of closed-source modules can only be200 determined by the courts. But the uncertainty which haunts those modules201 is there regardless.202 203- Binary modules greatly increase the difficulty of debugging kernel204 problems, to the point that most kernel developers will not even try. So205 the distribution of binary-only modules will make it harder for your206 users to get support from the community.207 208- Support is also harder for distributors of binary-only modules, who must209 provide a version of the module for every distribution and every kernel210 version they wish to support. Dozens of builds of a single module can211 be required to provide reasonably comprehensive coverage, and your users212 will have to upgrade your module separately every time they upgrade their213 kernel.214 215- Everything that was said above about code review applies doubly to216 closed-source code. Since this code is not available at all, it cannot217 have been reviewed by the community and will, beyond doubt, have serious218 problems.219 220Makers of embedded systems, in particular, may be tempted to disregard much221of what has been said in this section in the belief that they are shipping222a self-contained product which uses a frozen kernel version and requires no223more development after its release. This argument misses the value of224widespread code review and the value of allowing your users to add225capabilities to your product. But these products, too, have a limited226commercial life, after which a new version must be released. At that227point, vendors whose code is in the mainline and well maintained will be228much better positioned to get the new product ready for market quickly.229 230Licensing231---------232 233Code is contributed to the Linux kernel under a number of licenses, but all234code must be compatible with version 2 of the GNU General Public License235(GPLv2), which is the license covering the kernel distribution as a whole.236In practice, that means that all code contributions are covered either by237GPLv2 (with, optionally, language allowing distribution under later238versions of the GPL) or the three-clause BSD license. Any contributions239which are not covered by a compatible license will not be accepted into the240kernel.241 242Copyright assignments are not required (or requested) for code contributed243to the kernel. All code merged into the mainline kernel retains its244original ownership; as a result, the kernel now has thousands of owners.245 246One implication of this ownership structure is that any attempt to change247the licensing of the kernel is doomed to almost certain failure. There are248few practical scenarios where the agreement of all copyright holders could249be obtained (or their code removed from the kernel). So, in particular,250there is no prospect of a migration to version 3 of the GPL in the251foreseeable future.252 253It is imperative that all code contributed to the kernel be legitimately254free software. For that reason, code from anonymous (or pseudonymous)255contributors will not be accepted. All contributors are required to "sign256off" on their code, stating that the code can be distributed with the257kernel under the GPL. Code which has not been licensed as free software by258its owner, or which risks creating copyright-related problems for the259kernel (such as code which derives from reverse-engineering efforts lacking260proper safeguards) cannot be contributed.261 262Questions about copyright-related issues are common on Linux development263mailing lists. Such questions will normally receive no shortage of264answers, but one should bear in mind that the people answering those265questions are not lawyers and cannot provide legal advice. If you have266legal questions relating to Linux source code, there is no substitute for267talking with a lawyer who understands this field. Relying on answers268obtained on technical mailing lists is a risky affair.269