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