Documentation/process/1.Intro.rst

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