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