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