About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / development-process / 1.Intro


Based on kernel version 4.8. Page generated on 2016-10-06 23:10 EST.

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


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog