Commit | Line | Data |
---|---|---|
edba5eec FV |
1 | .. _development_process_intro: |
2 | ||
7d56f0fa S |
3 | Introduction |
4 | ============ | |
75b02146 | 5 | |
f7c9fe4b MCC |
6 | Executive summary |
7 | ----------------- | |
75b02146 JC |
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 | ||
f7c9fe4b MCC |
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 | |
75b02146 JC |
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 | ||
f7c9fe4b MCC |
24 | :ref:`development_early_stage` covers early-stage project planning, with an |
25 | emphasis on involving the development community as soon as possible. | |
75b02146 | 26 | |
f7c9fe4b MCC |
27 | :ref:`development_coding` is about the coding process; several pitfalls which |
28 | have been encountered by other developers are discussed. Some requirements for | |
75b02146 JC |
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 | ||
f7c9fe4b MCC |
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. | |
75b02146 JC |
35 | Following the advice in this section should help to ensure the best |
36 | possible reception for your work. | |
37 | ||
f7c9fe4b MCC |
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 | |
75b02146 JC |
42 | assuming that the job is done when a patch is merged into the mainline. |
43 | ||
f7c9fe4b MCC |
44 | :ref:`development_advancedtopics` introduces a couple of "advanced" topics: |
45 | managing patches with git and reviewing patches posted by others. | |
75b02146 | 46 | |
f7c9fe4b MCC |
47 | :ref:`development_conclusion` concludes the document with pointers to sources |
48 | for more information on kernel development. | |
75b02146 | 49 | |
f7c9fe4b MCC |
50 | What this document is about |
51 | --------------------------- | |
75b02146 | 52 | |
5c050fb9 JC |
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. | |
75b02146 JC |
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 | ||
f7c9fe4b MCC |
105 | Credits |
106 | ------- | |
75b02146 JC |
107 | |
108 | This document was written by Jonathan Corbet, corbet@lwn.net. 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 | |
5c050fb9 | 112 | Jochen Voß. |
75b02146 JC |
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 | ||
f7c9fe4b MCC |
117 | The importance of getting code into the mainline |
118 | ------------------------------------------------ | |
75b02146 JC |
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 | |
5c050fb9 | 218 | problems. |
75b02146 JC |
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 | ||
f7c9fe4b MCC |
230 | Licensing |
231 | --------- | |
75b02146 JC |
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 anonymous (or pseudonymous) | |
255 | contributors will not be accepted. All contributors are required to "sign | |
256 | off" on their code, stating that the code can be distributed with the | |
257 | kernel under the GPL. Code which has not been licensed as free software by | |
258 | its owner, or which risks creating copyright-related problems for the | |
259 | 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. |