3The purpose of this document is to help developers (and their managers)
   4work with the development community with a minimum of frustration.  It is
   5an attempt to document how this community works in a way which is
   6accessible to those who are not intimately familiar with Linux kernel
   7development (or, indeed, free software development in general).  While
   8there is some technical material here, this is very much a process-oriented
   9discussion which does not require a deep knowledge of kernel programming to
  15The rest of this section covers the scope of the kernel development process
  16and the kinds of frustrations that developers and their employers can
  17encounter there.  There are a great many reasons why kernel code should be
  18merged into the official ("mainline") kernel, including automatic
  19availability to users, community support in many forms, and the ability to
  20influence the direction of kernel development.  Code contributed to the
  21Linux kernel must be made available under a GPL-compatible license.
  23Section 2 introduces the development process, the kernel release cycle, and
  24the mechanics of the merge window.  The various phases in the patch
  25development, review, and merging cycle are covered.  There is some
  26discussion of tools and mailing lists.  Developers wanting to get started
  27with kernel development are encouraged to track down and fix bugs as an
  28initial exercise.
  30Section 3 covers early-stage project planning, with an emphasis on
  31involving the development community as soon as possible.
  33Section 4 is about the coding process; several pitfalls which have been
  34encountered by other developers are discussed.  Some requirements for
  35patches are covered, and there is an introduction to some of the tools
  36which can help to ensure that kernel patches are correct.
  38Section 5 talks about the process of posting patches for review.  To be
  39taken seriously by the development community, patches must be properly
  40formatted and described, and they must be sent to the right place.
  41Following the advice in this section should help to ensure the best
  42possible reception for your work.
  44Section 6 covers what happens after posting patches; the job is far from
  45done at that point.  Working with reviewers is a crucial part of the
  46development process; this section offers a number of tips on how to avoid
  47problems at this important stage.  Developers are cautioned against
  48assuming that the job is done when a patch is merged into the mainline.
  50Section 7 introduces a couple of "advanced" topics: managing patches with
  51git and reviewing patches posted by others.
  53Section 8 concludes the document with pointers to sources for more
  54information on kernel development.
  59The Linux kernel, at over 6 million lines of code and well over 1000 active
  60contributors, is one of the largest and most active free software projects
  61in existence.  Since its humble beginning in 1991, this kernel has evolved
  62into a best-of-breed operating system component which runs on pocket-sized
  63digital music players, desktop PCs, the largest supercomputers in
  64existence, and all types of systems in between.  It is a robust, efficient,
  65and scalable solution for almost any situation.
  67With the growth of Linux has come an increase in the number of developers
  68(and companies) wishing to participate in its development.  Hardware
  69vendors want to ensure that Linux supports their products well, making
  70those products attractive to Linux users.  Embedded systems vendors, who
  71use Linux as a component in an integrated product, want Linux to be as
  72capable and well-suited to the task at hand as possible.  Distributors and
  73other software vendors who base their products on Linux have a clear
  74interest in the capabilities, performance, and reliability of the Linux
  75kernel.  And end users, too, will often wish to change Linux to make it
  76better suit their needs.
  78One of the most compelling features of Linux is that it is accessible to
  79these developers; anybody with the requisite skills can improve Linux and
  80influence the direction of its development.  Proprietary products cannot
  81offer this kind of openness, which is a characteristic of the free software
  82process.  But, if anything, the kernel is even more open than most other
  83free software projects.  A typical three-month kernel development cycle can
  84involve over 1000 developers working for more than 100 different companies
  85(or for no company at all).
  87Working with the kernel development community is not especially hard.  But,
  88that notwithstanding, many potential contributors have experienced
  89difficulties when trying to do kernel work.  The kernel community has
  90evolved its own distinct ways of operating which allow it to function
  91smoothly (and produce a high-quality product) in an environment where
  92thousands of lines of code are being changed every day.  So it is not
  93surprising that Linux kernel development process differs greatly from
  94proprietary development methods.
  96The kernel's development process may come across as strange and
  97intimidating to new developers, but there are good reasons and solid
  98experience behind it.  A developer who does not understand the kernel
  99community's ways (or, worse, who tries to flout or circumvent them) will
 100have a frustrating experience in store.  The development community, while
 101being helpful to those who are trying to learn, has little time for those
 102who will not listen or who do not care about the development process.
 104It is hoped that those who read this document will be able to avoid that
 105frustrating experience.  There is a lot of material here, but the effort
 106involved in reading it will be repaid in short order.  The development
 107community is always in need of developers who will help to make the kernel
 108better; the following text should help you - or those who work for you -
 109join our community.
 1121.3: CREDITS
 114This document was written by Jonathan Corbet,  It has been
 115improved by comments from Johannes Berg, James Berry, Alex Chiang, Roland
 116Dreier, Randy Dunlap, Jake Edge, Jiri Kosina, Matt Mackall, Arthur Marsh,
 117Amanda McPherson, Andrew Morton, Andrew Price, Tsugikazu Shibata, and
 118Jochen Vo\xC3\x9F. 
 120This work was supported by the Linux Foundation; thanks especially to
 121Amanda McPherson, who saw the value of this effort and made it all happen.
 126Some companies and developers occasionally wonder why they should bother
 127learning how to work with the kernel community and get their code into the
 128mainline kernel (the "mainline" being the kernel maintained by Linus
 129Torvalds and used as a base by Linux distributors).  In the short term,
 130contributing code can look like an avoidable expense; it seems easier to
 131just keep the code separate and support users directly.  The truth of the
 132matter is that keeping code separate ("out of tree") is a false economy.
 134As a way of illustrating the costs of out-of-tree code, here are a few
 135relevant aspects of the kernel development process; most of these will be
 136discussed in greater detail later in this document.  Consider:
 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.
 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.
 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.
 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.
 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.
 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.
 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.
 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.
 193All of the reasoning above applies to any out-of-tree kernel code,
 194including code which is distributed in proprietary, binary-only form.
 195There are, however, additional factors which should be taken into account
 196before considering any sort of binary-only kernel code distribution.  These
 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.
 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.
 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.
 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. 
 226Makers of embedded systems, in particular, may be tempted to disregard much
 227of what has been said in this section in the belief that they are shipping
 228a self-contained product which uses a frozen kernel version and requires no
 229more development after its release.  This argument misses the value of
 230widespread code review and the value of allowing your users to add
 231capabilities to your product.  But these products, too, have a limited
 232commercial life, after which a new version must be released.  At that
 233point, vendors whose code is in the mainline and well maintained will be
 234much better positioned to get the new product ready for market quickly.
 2371.5: LICENSING
 239Code is contributed to the Linux kernel under a number of licenses, but all
 240code 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.
 242In practice, that means that all code contributions are covered either by
 243GPLv2 (with, optionally, language allowing distribution under later
 244versions of the GPL) or the three-clause BSD license.  Any contributions
 245which are not covered by a compatible license will not be accepted into the
 248Copyright assignments are not required (or requested) for code contributed
 249to the kernel.  All code merged into the mainline kernel retains its
 250original ownership; as a result, the kernel now has thousands of owners.
 252One implication of this ownership structure is that any attempt to change
 253the licensing of the kernel is doomed to almost certain failure.  There are
 254few practical scenarios where the agreement of all copyright holders could
 255be obtained (or their code removed from the kernel).  So, in particular,
 256there is no prospect of a migration to version 3 of the GPL in the
 257foreseeable future.
 259It is imperative that all code contributed to the kernel be legitimately
 260free software.  For that reason, code from anonymous (or pseudonymous)
 261contributors will not be accepted.  All contributors are required to "sign
 262off" on their code, stating that the code can be distributed with the
 263kernel under the GPL.  Code which has not been licensed as free software by
 264its owner, or which risks creating copyright-related problems for the
 265kernel (such as code which derives from reverse-engineering efforts lacking
 266proper safeguards) cannot be contributed.
 268Questions about copyright-related issues are common on Linux development
 269mailing lists.  Such questions will normally receive no shortage of
 270answers, but one should bear in mind that the people answering those
 271questions are not lawyers and cannot provide legal advice.  If you have
 272legal questions relating to Linux source code, there is no substitute for
 273talking with a lawyer who understands this field.  Relying on answers
 274obtained on technical mailing lists is a risky affair.