1.1.Executive summary¶

The rest of this section covers the scope of the kernel development processand the kinds of frustrations that developers and their employers canencounter there. There are a great many reasons why kernel code should bemerged into the official (“mainline”) kernel, including automaticavailability to users, community support in many forms, and the ability toinfluence the direction of kernel development. Code contributed to theLinux kernel must be made available under a GPL-compatible license.

How the development process works introduces the development process, the kernelrelease cycle, and the mechanics of the merge window. The various phases inthe patch development, review, and merging cycle are covered. There is somediscussion of tools and mailing lists. Developers wanting to get startedwith kernel development are encouraged to track down and fix bugs as aninitial exercise.

Early-stage planning covers early-stage project planning, with anemphasis on involving the development community as soon as possible.

Getting the code right is about the coding process; several pitfalls whichhave been encountered by other developers are discussed. Some requirements forpatches are covered, and there is an introduction to some of the toolswhich can help to ensure that kernel patches are correct.

Posting patches talks about the process of posting patches forreview. To be taken seriously by the development community, patches must beproperly formatted and described, and they must be sent to the right place.Following the advice in this section should help to ensure the bestpossible reception for your work.

Followthrough covers what happens after posting patches; thejob is far from done at that point. Working with reviewers is a crucial partof the development process; this section offers a number of tips on how toavoid problems at this important stage. Developers are cautioned againstassuming that the job is done when a patch is merged into the mainline.

Advanced topics introduces a couple of “advanced” topics:managing patches with git and reviewing patches posted by others.

For more information concludes the document with pointers to sourcesfor more information on kernel development.

1.2.What this document is about¶

The Linux kernel, at over 8 million lines of code and well over 1000contributors to each release, is one of the largest and most active freesoftware projects in existence. Since its humble beginning in 1991, thiskernel has evolved into a best-of-breed operating system component whichruns on pocket-sized digital music players, desktop PCs, the largestsupercomputers in existence, and all types of systems in between. It is arobust, efficient, and scalable solution for almost any situation.

With the growth of Linux has come an increase in the number of developers(and companies) wishing to participate in its development. Hardwarevendors want to ensure that Linux supports their products well, makingthose products attractive to Linux users. Embedded systems vendors, whouse Linux as a component in an integrated product, want Linux to be ascapable and well-suited to the task at hand as possible. Distributors andother software vendors who base their products on Linux have a clearinterest in the capabilities, performance, and reliability of the Linuxkernel. And end users, too, will often wish to change Linux to make itbetter suit their needs.

One of the most compelling features of Linux is that it is accessible tothese developers; anybody with the requisite skills can improve Linux andinfluence the direction of its development. Proprietary products cannotoffer this kind of openness, which is a characteristic of the free softwareprocess. But, if anything, the kernel is even more open than most otherfree software projects. A typical three-month kernel development cycle caninvolve over 1000 developers working for more than 100 different companies(or for no company at all).

Working with the kernel development community is not especially hard. But,that notwithstanding, many potential contributors have experienceddifficulties when trying to do kernel work. The kernel community hasevolved its own distinct ways of operating which allow it to functionsmoothly (and produce a high-quality product) in an environment wherethousands of lines of code are being changed every day. So it is notsurprising that Linux kernel development process differs greatly fromproprietary development methods.

The kernel’s development process may come across as strange andintimidating to new developers, but there are good reasons and solidexperience behind it. A developer who does not understand the kernelcommunity’s ways (or, worse, who tries to flout or circumvent them) willhave a frustrating experience in store. The development community, whilebeing helpful to those who are trying to learn, has little time for thosewho will not listen or who do not care about the development process.

It is hoped that those who read this document will be able to avoid thatfrustrating experience. There is a lot of material here, but the effortinvolved in reading it will be repaid in short order. The developmentcommunity is always in need of developers who will help to make the kernelbetter; the following text should help you - or those who work for you -join our community.

1.3.Credits¶

This document was written by Jonathan Corbet,corbet@lwn.net. It has beenimproved by comments from Johannes Berg, James Berry, Alex Chiang, RolandDreier, Randy Dunlap, Jake Edge, Jiri Kosina, Matt Mackall, Arthur Marsh,Amanda McPherson, Andrew Morton, Andrew Price, Tsugikazu Shibata, andJochen Voß.

This work was supported by the Linux Foundation; thanks especially toAmanda McPherson, who saw the value of this effort and made it all happen.

1.4.The importance of getting code into the mainline¶

Some companies and developers occasionally wonder why they should botherlearning how to work with the kernel community and get their code into themainline kernel (the “mainline” being the kernel maintained by LinusTorvalds and used as a base by Linux distributors). In the short term,contributing code can look like an avoidable expense; it seems easier tojust keep the code separate and support users directly. The truth of thematter is that keeping code separate (“out of tree”) is a false economy.

As a way of illustrating the costs of out-of-tree code, here are a fewrelevant aspects of the kernel development process; most of these will bediscussed in greater detail later in this document. Consider:

• Code which has been merged into the mainline kernel is available to allLinux users. It will automatically be present on all distributions whichenable it. There is no need for driver disks, downloads, or the hasslesof supporting multiple versions of multiple distributions; it all justworks, for the developer and for the user. Incorporation into themainline solves a large number of distribution and support problems.

• While kernel developers strive to maintain a stable interface to userspace, the internal kernel API is in constant flux. The lack of a stableinternal interface is a deliberate design decision; it allows fundamentalimprovements to be made at any time and results in higher-quality code.But one result of that policy is that any out-of-tree code requiresconstant upkeep if it is to work with new kernels. Maintainingout-of-tree code requires significant amounts of work just to keep thatcode working.

  Code which is in the mainline, instead, does not require this work as theresult of a simple rule requiring any developer who makes an API changeto also fix any code that breaks as the result of that change. So codewhich has been merged into the mainline has significantly lowermaintenance costs.

• Beyond that, code which is in the kernel will often be improved by otherdevelopers. Surprising results can come from empowering your usercommunity and customers to improve your product.

• Kernel code is subjected to review, both before and after merging intothe mainline. No matter how strong the original developer’s skills are,this review process invariably finds ways in which the code can beimproved. Often review finds severe bugs and security problems. This isespecially true for code which has been developed in a closedenvironment; such code benefits strongly from review by outsidedevelopers. Out-of-tree code is lower-quality code.

• Participation in the development process is your way to influence thedirection of kernel development. Users who complain from the sidelinesare heard, but active developers have a stronger voice - and the abilityto implement changes which make the kernel work better for their needs.

• When code is maintained separately, the possibility that a third partywill contribute a different implementation of a similar feature alwaysexists. Should that happen, getting your code merged will become muchharder - to the point of impossibility. Then you will be faced with theunpleasant alternatives of either (1) maintaining a nonstandard featureout of tree indefinitely, or (2) abandoning your code and migrating yourusers over to the in-tree version.

• Contribution of code is the fundamental action which makes the wholeprocess work. By contributing your code you can add new functionality tothe kernel and provide capabilities and examples which are of use toother kernel developers. If you have developed code for Linux (or arethinking about doing so), you clearly have an interest in the continuedsuccess of this platform; contributing code is one of the best ways tohelp ensure that success.

All of the reasoning above applies to any out-of-tree kernel code,including code which is distributed in proprietary, binary-only form.There are, however, additional factors which should be taken into accountbefore considering any sort of binary-only kernel code distribution. Theseinclude:

• The legal issues around the distribution of proprietary kernel modulesare cloudy at best; quite a few kernel copyright holders believe thatmost binary-only modules are derived products of the kernel and that, asa result, their distribution is a violation of the GNU General Publiclicense (about which more will be said below). Your author is not alawyer, and nothing in this document can possibly be considered to belegal advice. The true legal status of closed-source modules can only bedetermined by the courts. But the uncertainty which haunts those modulesis there regardless.

• Binary modules greatly increase the difficulty of debugging kernelproblems, to the point that most kernel developers will not even try. Sothe distribution of binary-only modules will make it harder for yourusers to get support from the community.

• Support is also harder for distributors of binary-only modules, who mustprovide a version of the module for every distribution and every kernelversion they wish to support. Dozens of builds of a single module canbe required to provide reasonably comprehensive coverage, and your userswill have to upgrade your module separately every time they upgrade theirkernel.

• Everything that was said above about code review applies doubly toclosed-source code. Since this code is not available at all, it cannothave been reviewed by the community and will, beyond doubt, have seriousproblems.

Makers of embedded systems, in particular, may be tempted to disregard muchof what has been said in this section in the belief that they are shippinga self-contained product which uses a frozen kernel version and requires nomore development after its release. This argument misses the value ofwidespread code review and the value of allowing your users to addcapabilities to your product. But these products, too, have a limitedcommercial life, after which a new version must be released. At thatpoint, vendors whose code is in the mainline and well maintained will bemuch better positioned to get the new product ready for market quickly.

1.5.Licensing¶

Code is contributed to the Linux kernel under a number of licenses, but allcode must be compatible with version 2 of the GNU General Public License(GPLv2), which is the license covering the kernel distribution as a whole.In practice, that means that all code contributions are covered either byGPLv2 (with, optionally, language allowing distribution under laterversions of the GPL) or the three-clause BSD license. Any contributionswhich are not covered by a compatible license will not be accepted into thekernel.

Copyright assignments are not required (or requested) for code contributedto the kernel. All code merged into the mainline kernel retains itsoriginal ownership; as a result, the kernel now has thousands of owners.

One implication of this ownership structure is that any attempt to changethe licensing of the kernel is doomed to almost certain failure. There arefew practical scenarios where the agreement of all copyright holders couldbe obtained (or their code removed from the kernel). So, in particular,there is no prospect of a migration to version 3 of the GPL in theforeseeable future.

It is imperative that all code contributed to the kernel be legitimatelyfree software. For that reason, code from contributors without a knownidentity or anonymous contributors will not be accepted. All contributors arerequired to “sign off” on their code, stating that the code can be distributedwith the kernel under the GPL. Code which has not been licensed as freesoftware by its owner, or which risks creating copyright-related problems forthe kernel (such as code which derives from reverse-engineering efforts lackingproper safeguards) cannot be contributed.

Questions about copyright-related issues are common on Linux developmentmailing lists. Such questions will normally receive no shortage ofanswers, but one should bear in mind that the people answering thosequestions are not lawyers and cannot provide legal advice. If you havelegal questions relating to Linux source code, there is no substitute fortalking with a lawyer who understands this field. Relying on answersobtained on technical mailing lists is a risky affair.