Commit f7c9fe4b authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by Jonathan Corbet

doc: development-process: convert it to ReST markup

This document is on good shape for ReST: all it was needed was
to fix the section markups, add a toctree, convert the tables
and add a few code/quote blocks.

While not strictly required, I opted to use lowercase for
the titles, just like the other books that were converted
to Sphinx.
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
parent 1414f048
1: A GUIDE TO THE KERNEL DEVELOPMENT PROCESS Introdution
===========
The purpose of this document is to help developers (and their managers) Executive summary
work with the development community with a minimum of frustration. It is -----------------
an attempt to document how this community works in a way which is
accessible to those who are not intimately familiar with Linux kernel
development (or, indeed, free software development in general). While
there is some technical material here, this is very much a process-oriented
discussion which does not require a deep knowledge of kernel programming to
understand.
1.1: EXECUTIVE SUMMARY
The rest of this section covers the scope of the kernel development process The rest of this section covers the scope of the kernel development process
and the kinds of frustrations that developers and their employers can and the kinds of frustrations that developers and their employers can
...@@ -20,41 +12,41 @@ availability to users, community support in many forms, and the ability to ...@@ -20,41 +12,41 @@ availability to users, community support in many forms, and the ability to
influence the direction of kernel development. Code contributed to the influence the direction of kernel development. Code contributed to the
Linux kernel must be made available under a GPL-compatible license. Linux kernel must be made available under a GPL-compatible license.
Section 2 introduces the development process, the kernel release cycle, and :ref:`development_process` introduces the development process, the kernel
the mechanics of the merge window. The various phases in the patch release cycle, and the mechanics of the merge window. The various phases in
development, review, and merging cycle are covered. There is some the patch development, review, and merging cycle are covered. There is some
discussion of tools and mailing lists. Developers wanting to get started discussion of tools and mailing lists. Developers wanting to get started
with kernel development are encouraged to track down and fix bugs as an with kernel development are encouraged to track down and fix bugs as an
initial exercise. initial exercise.
Section 3 covers early-stage project planning, with an emphasis on :ref:`development_early_stage` covers early-stage project planning, with an
involving the development community as soon as possible. emphasis on involving the development community as soon as possible.
Section 4 is about the coding process; several pitfalls which have been :ref:`development_coding` is about the coding process; several pitfalls which
encountered by other developers are discussed. Some requirements for have been encountered by other developers are discussed. Some requirements for
patches are covered, and there is an introduction to some of the tools patches are covered, and there is an introduction to some of the tools
which can help to ensure that kernel patches are correct. which can help to ensure that kernel patches are correct.
Section 5 talks about the process of posting patches for review. To be :ref:`development_posting` talks about the process of posting patches for
taken seriously by the development community, patches must be properly review. To be taken seriously by the development community, patches must be
formatted and described, and they must be sent to the right place. properly formatted and described, and they must be sent to the right place.
Following the advice in this section should help to ensure the best Following the advice in this section should help to ensure the best
possible reception for your work. possible reception for your work.
Section 6 covers what happens after posting patches; the job is far from :ref:`development_followthrough` covers what happens after posting patches; the
done at that point. Working with reviewers is a crucial part of the job is far from done at that point. Working with reviewers is a crucial part
development process; this section offers a number of tips on how to avoid of the development process; this section offers a number of tips on how to
problems at this important stage. Developers are cautioned against avoid problems at this important stage. Developers are cautioned against
assuming that the job is done when a patch is merged into the mainline. assuming that the job is done when a patch is merged into the mainline.
Section 7 introduces a couple of "advanced" topics: managing patches with :ref:`development_advancedtopics` introduces a couple of "advanced" topics:
git and reviewing patches posted by others. managing patches with git and reviewing patches posted by others.
Section 8 concludes the document with pointers to sources for more
information on kernel development.
:ref:`development_conclusion` concludes the document with pointers to sources
for more information on kernel development.
1.2: WHAT THIS DOCUMENT IS ABOUT What this document is about
---------------------------
The Linux kernel, at over 8 million lines of code and well over 1000 The Linux kernel, at over 8 million lines of code and well over 1000
contributors to each release, is one of the largest and most active free contributors to each release, is one of the largest and most active free
...@@ -108,8 +100,8 @@ community is always in need of developers who will help to make the kernel ...@@ -108,8 +100,8 @@ community is always in need of developers who will help to make the kernel
better; the following text should help you - or those who work for you - better; the following text should help you - or those who work for you -
join our community. join our community.
Credits
1.3: CREDITS -------
This document was written by Jonathan Corbet, corbet@lwn.net. It has been This document was written by Jonathan Corbet, corbet@lwn.net. It has been
improved by comments from Johannes Berg, James Berry, Alex Chiang, Roland improved by comments from Johannes Berg, James Berry, Alex Chiang, Roland
...@@ -120,8 +112,8 @@ Jochen Voß. ...@@ -120,8 +112,8 @@ Jochen Voß.
This work was supported by the Linux Foundation; thanks especially to This work was supported by the Linux Foundation; thanks especially to
Amanda McPherson, who saw the value of this effort and made it all happen. Amanda McPherson, who saw the value of this effort and made it all happen.
The importance of getting code into the mainline
1.4: THE IMPORTANCE OF GETTING CODE INTO THE MAINLINE ------------------------------------------------
Some companies and developers occasionally wonder why they should bother Some companies and developers occasionally wonder why they should bother
learning how to work with the kernel community and get their code into the learning how to work with the kernel community and get their code into the
...@@ -233,8 +225,8 @@ commercial life, after which a new version must be released. At that ...@@ -233,8 +225,8 @@ commercial life, after which a new version must be released. At that
point, vendors whose code is in the mainline and well maintained will be point, vendors whose code is in the mainline and well maintained will be
much better positioned to get the new product ready for market quickly. much better positioned to get the new product ready for market quickly.
Licensing
1.5: LICENSING ---------
Code is contributed to the Linux kernel under a number of licenses, but all Code is contributed to the Linux kernel under a number of licenses, but all
code must be compatible with version 2 of the GNU General Public License code must be compatible with version 2 of the GNU General Public License
......
2: HOW THE DEVELOPMENT PROCESS WORKS .. _development_process:
How the development process works
=================================
Linux kernel development in the early 1990's was a pretty loose affair, Linux kernel development in the early 1990's was a pretty loose affair,
with relatively small numbers of users and developers involved. With a with relatively small numbers of users and developers involved. With a
...@@ -7,19 +10,21 @@ course of one year, the kernel has since had to evolve a number of ...@@ -7,19 +10,21 @@ course of one year, the kernel has since had to evolve a number of
processes to keep development happening smoothly. A solid understanding of processes to keep development happening smoothly. A solid understanding of
how the process works is required in order to be an effective part of it. how the process works is required in order to be an effective part of it.
The big picture
2.1: THE BIG PICTURE ---------------
The kernel developers use a loosely time-based release process, with a new The kernel developers use a loosely time-based release process, with a new
major kernel release happening every two or three months. The recent major kernel release happening every two or three months. The recent
release history looks like this: release history looks like this:
====== =================
2.6.38 March 14, 2011 2.6.38 March 14, 2011
2.6.37 January 4, 2011 2.6.37 January 4, 2011
2.6.36 October 20, 2010 2.6.36 October 20, 2010
2.6.35 August 1, 2010 2.6.35 August 1, 2010
2.6.34 May 15, 2010 2.6.34 May 15, 2010
2.6.33 February 24, 2010 2.6.33 February 24, 2010
====== =================
Every 2.6.x release is a major kernel release with new features, internal Every 2.6.x release is a major kernel release with new features, internal
API changes, and more. A typical 2.6 release can contain nearly 10,000 API changes, and more. A typical 2.6 release can contain nearly 10,000
...@@ -68,6 +73,7 @@ At that point the whole process starts over again. ...@@ -68,6 +73,7 @@ At that point the whole process starts over again.
As an example, here is how the 2.6.38 development cycle went (all dates in As an example, here is how the 2.6.38 development cycle went (all dates in
2011): 2011):
============== ===============================
January 4 2.6.37 stable release January 4 2.6.37 stable release
January 18 2.6.38-rc1, merge window closes January 18 2.6.38-rc1, merge window closes
January 21 2.6.38-rc2 January 21 2.6.38-rc2
...@@ -78,6 +84,7 @@ As an example, here is how the 2.6.38 development cycle went (all dates in ...@@ -78,6 +84,7 @@ As an example, here is how the 2.6.38 development cycle went (all dates in
March 1 2.6.38-rc7 March 1 2.6.38-rc7
March 7 2.6.38-rc8 March 7 2.6.38-rc8
March 14 2.6.38 stable release March 14 2.6.38 stable release
============== ===============================
How do the developers decide when to close the development cycle and create How do the developers decide when to close the development cycle and create
the stable release? The most significant metric used is the list of the stable release? The most significant metric used is the list of
...@@ -105,11 +112,13 @@ next development kernel. Kernels will typically receive stable updates for ...@@ -105,11 +112,13 @@ next development kernel. Kernels will typically receive stable updates for
a little more than one development cycle past their initial release. So, a little more than one development cycle past their initial release. So,
for example, the 2.6.36 kernel's history looked like: for example, the 2.6.36 kernel's history looked like:
============== ===============================
October 10 2.6.36 stable release October 10 2.6.36 stable release
November 22 2.6.36.1 November 22 2.6.36.1
December 9 2.6.36.2 December 9 2.6.36.2
January 7 2.6.36.3 January 7 2.6.36.3
February 17 2.6.36.4 February 17 2.6.36.4
============== ===============================
2.6.36.4 was the final stable update for the 2.6.36 release. 2.6.36.4 was the final stable update for the 2.6.36 release.
...@@ -117,9 +126,11 @@ Some kernels are designated "long term" kernels; they will receive support ...@@ -117,9 +126,11 @@ Some kernels are designated "long term" kernels; they will receive support
for a longer period. As of this writing, the current long term kernels for a longer period. As of this writing, the current long term kernels
and their maintainers are: and their maintainers are:
====== ====================== ===========================
2.6.27 Willy Tarreau (Deep-frozen stable kernel) 2.6.27 Willy Tarreau (Deep-frozen stable kernel)
2.6.32 Greg Kroah-Hartman 2.6.32 Greg Kroah-Hartman
2.6.35 Andi Kleen (Embedded flag kernel) 2.6.35 Andi Kleen (Embedded flag kernel)
====== ====================== ===========================
The selection of a kernel for long-term support is purely a matter of a The selection of a kernel for long-term support is purely a matter of a
maintainer having the need and the time to maintain that release. There maintainer having the need and the time to maintain that release. There
...@@ -127,7 +138,8 @@ are no known plans for long-term support for any specific upcoming ...@@ -127,7 +138,8 @@ are no known plans for long-term support for any specific upcoming
release. release.
2.2: THE LIFECYCLE OF A PATCH The lifecycle of a patch
------------------------
Patches do not go directly from the developer's keyboard into the mainline Patches do not go directly from the developer's keyboard into the mainline
kernel. There is, instead, a somewhat involved (if somewhat informal) kernel. There is, instead, a somewhat involved (if somewhat informal)
...@@ -195,8 +207,8 @@ is to try to cut the process down to a single "merging into the mainline" ...@@ -195,8 +207,8 @@ is to try to cut the process down to a single "merging into the mainline"
step. This approach invariably leads to frustration for everybody step. This approach invariably leads to frustration for everybody
involved. involved.
How patches get into the Kernel
2.3: HOW PATCHES GET INTO THE KERNEL -------------------------------
There is exactly one person who can merge patches into the mainline kernel There is exactly one person who can merge patches into the mainline kernel
repository: Linus Torvalds. But, of the over 9,500 patches which went repository: Linus Torvalds. But, of the over 9,500 patches which went
...@@ -242,7 +254,8 @@ finding the right maintainer. Sending patches directly to Linus is not ...@@ -242,7 +254,8 @@ finding the right maintainer. Sending patches directly to Linus is not
normally the right way to go. normally the right way to go.
2.4: NEXT TREES Next trees
----------
The chain of subsystem trees guides the flow of patches into the kernel, The chain of subsystem trees guides the flow of patches into the kernel,
but it also raises an interesting question: what if somebody wants to look but it also raises an interesting question: what if somebody wants to look
...@@ -294,7 +307,8 @@ all patches merged during a given merge window should really have found ...@@ -294,7 +307,8 @@ all patches merged during a given merge window should really have found
their way into linux-next some time before the merge window opens. their way into linux-next some time before the merge window opens.
2.4.1: STAGING TREES Staging trees
-------------
The kernel source tree contains the drivers/staging/ directory, where The kernel source tree contains the drivers/staging/ directory, where
many sub-directories for drivers or filesystems that are on their way to many sub-directories for drivers or filesystems that are on their way to
...@@ -322,7 +336,8 @@ staging drivers. So staging is, at best, a stop on the way toward becoming ...@@ -322,7 +336,8 @@ staging drivers. So staging is, at best, a stop on the way toward becoming
a proper mainline driver. a proper mainline driver.
2.5: TOOLS Tools
-----
As can be seen from the above text, the kernel development process depends As can be seen from the above text, the kernel development process depends
heavily on the ability to herd collections of patches in various heavily on the ability to herd collections of patches in various
...@@ -368,7 +383,8 @@ upstream. For the management of certain kinds of trees (-mm, for example), ...@@ -368,7 +383,8 @@ upstream. For the management of certain kinds of trees (-mm, for example),
quilt is the best tool for the job. quilt is the best tool for the job.
2.6: MAILING LISTS Mailing lists
-------------
A great deal of Linux kernel development work is done by way of mailing A great deal of Linux kernel development work is done by way of mailing
lists. It is hard to be a fully-functioning member of the community lists. It is hard to be a fully-functioning member of the community
...@@ -436,7 +452,8 @@ filesystem, etc. subsystems. The best place to look for mailing lists is ...@@ -436,7 +452,8 @@ filesystem, etc. subsystems. The best place to look for mailing lists is
in the MAINTAINERS file packaged with the kernel source. in the MAINTAINERS file packaged with the kernel source.
2.7: GETTING STARTED WITH KERNEL DEVELOPMENT Getting started with Kernel development
---------------------------------------
Questions about how to get started with the kernel development process are Questions about how to get started with the kernel development process are
common - from both individuals and companies. Equally common are missteps common - from both individuals and companies. Equally common are missteps
...@@ -463,6 +480,8 @@ they wish for by these means. ...@@ -463,6 +480,8 @@ they wish for by these means.
Andrew Morton gives this advice for aspiring kernel developers Andrew Morton gives this advice for aspiring kernel developers
::
The #1 project for all kernel beginners should surely be "make sure The #1 project for all kernel beginners should surely be "make sure
that the kernel runs perfectly at all times on all machines which that the kernel runs perfectly at all times on all machines which
you can lay your hands on". Usually the way to do this is to work you can lay your hands on". Usually the way to do this is to work
......
3: EARLY-STAGE PLANNING .. _development_early_stage:
Early-stage planning
====================
When contemplating a Linux kernel development project, it can be tempting When contemplating a Linux kernel development project, it can be tempting
to jump right in and start coding. As with any significant project, to jump right in and start coding. As with any significant project,
...@@ -7,7 +10,8 @@ line of code is written. Some time spent in early planning and ...@@ -7,7 +10,8 @@ line of code is written. Some time spent in early planning and
communication can save far more time later on. communication can save far more time later on.
3.1: SPECIFYING THE PROBLEM Specifying the problem
----------------------
Like any engineering project, a successful kernel enhancement starts with a Like any engineering project, a successful kernel enhancement starts with a
clear description of the problem to be solved. In some cases, this step is clear description of the problem to be solved. In some cases, this step is
...@@ -64,7 +68,8 @@ answers to a short set of questions: ...@@ -64,7 +68,8 @@ answers to a short set of questions:
Only then does it make sense to start considering possible solutions. Only then does it make sense to start considering possible solutions.
3.2: EARLY DISCUSSION Early discussion
----------------
When planning a kernel development project, it makes great sense to hold When planning a kernel development project, it makes great sense to hold
discussions with the community before launching into implementation. Early discussions with the community before launching into implementation. Early
...@@ -117,7 +122,8 @@ In each of these cases, a great deal of pain and extra work could have been ...@@ -117,7 +122,8 @@ In each of these cases, a great deal of pain and extra work could have been
avoided with some early discussion with the kernel developers. avoided with some early discussion with the kernel developers.
3.3: WHO DO YOU TALK TO? Who do you talk to?
-------------------
When developers decide to take their plans public, the next question will When developers decide to take their plans public, the next question will
be: where do we start? The answer is to find the right mailing list(s) and be: where do we start? The answer is to find the right mailing list(s) and
...@@ -141,6 +147,8 @@ development project. ...@@ -141,6 +147,8 @@ development project.
The task of finding the right maintainer is sometimes challenging enough The task of finding the right maintainer is sometimes challenging enough
that the kernel developers have added a script to ease the process: that the kernel developers have added a script to ease the process:
::
.../scripts/get_maintainer.pl .../scripts/get_maintainer.pl
This script will return the current maintainer(s) for a given file or This script will return the current maintainer(s) for a given file or
...@@ -155,7 +163,8 @@ If all else fails, talking to Andrew Morton can be an effective way to ...@@ -155,7 +163,8 @@ If all else fails, talking to Andrew Morton can be an effective way to
track down a maintainer for a specific piece of code. track down a maintainer for a specific piece of code.
3.4: WHEN TO POST? When to post?
-------------
If possible, posting your plans during the early stages can only be If possible, posting your plans during the early stages can only be
helpful. Describe the problem being solved and any plans that have been helpful. Describe the problem being solved and any plans that have been
...@@ -179,7 +188,8 @@ idea. The best thing to do in this situation is to proceed, keeping the ...@@ -179,7 +188,8 @@ idea. The best thing to do in this situation is to proceed, keeping the
community informed as you go. community informed as you go.
3.5: GETTING OFFICIAL BUY-IN Getting official buy-in
-----------------------
If your work is being done in a corporate environment - as most Linux If your work is being done in a corporate environment - as most Linux
kernel work is - you must, obviously, have permission from suitably kernel work is - you must, obviously, have permission from suitably
......
4: GETTING THE CODE RIGHT .. _development_coding:
Getting the code right
======================
While there is much to be said for a solid and community-oriented design While there is much to be said for a solid and community-oriented design
process, the proof of any kernel development project is in the resulting process, the proof of any kernel development project is in the resulting
...@@ -12,9 +15,11 @@ will shift toward doing things right and the tools which can help in that ...@@ -12,9 +15,11 @@ will shift toward doing things right and the tools which can help in that
quest. quest.
4.1: PITFALLS Pitfalls
---------
* Coding style Coding style
************
The kernel has long had a standard coding style, described in The kernel has long had a standard coding style, described in
Documentation/CodingStyle. For much of that time, the policies described Documentation/CodingStyle. For much of that time, the policies described
...@@ -54,7 +59,8 @@ style (a line which becomes far less readable if split to fit within the ...@@ -54,7 +59,8 @@ style (a line which becomes far less readable if split to fit within the
80-column limit, for example), just do it. 80-column limit, for example), just do it.
* Abstraction layers Abstraction layers
******************
Computer Science professors teach students to make extensive use of Computer Science professors teach students to make extensive use of
abstraction layers in the name of flexibility and information hiding. abstraction layers in the name of flexibility and information hiding.
...@@ -87,7 +93,8 @@ implement that functionality at a higher level. There is no value in ...@@ -87,7 +93,8 @@ implement that functionality at a higher level. There is no value in
replicating the same code throughout the kernel. replicating the same code throughout the kernel.
* #ifdef and preprocessor use in general #ifdef and preprocessor use in general
**************************************
The C preprocessor seems to present a powerful temptation to some C The C preprocessor seems to present a powerful temptation to some C
programmers, who see it as a way to efficiently encode a great deal of programmers, who see it as a way to efficiently encode a great deal of
...@@ -113,7 +120,8 @@ easier to read, do not evaluate their arguments multiple times, and allow ...@@ -113,7 +120,8 @@ easier to read, do not evaluate their arguments multiple times, and allow
the compiler to perform type checking on the arguments and return value. the compiler to perform type checking on the arguments and return value.
* Inline functions Inline functions
****************
Inline functions present a hazard of their own, though. Programmers can Inline functions present a hazard of their own, though. Programmers can
become enamored of the perceived efficiency inherent in avoiding a function become enamored of the perceived efficiency inherent in avoiding a function
...@@ -137,7 +145,8 @@ placement of "inline" keywords may not just be excessive; it could also be ...@@ -137,7 +145,8 @@ placement of "inline" keywords may not just be excessive; it could also be
irrelevant. irrelevant.
* Locking Locking
*******
In May, 2006, the "Devicescape" networking stack was, with great In May, 2006, the "Devicescape" networking stack was, with great
fanfare, released under the GPL and made available for inclusion in the fanfare, released under the GPL and made available for inclusion in the
...@@ -151,7 +160,7 @@ This code showed a number of signs of having been developed behind ...@@ -151,7 +160,7 @@ This code showed a number of signs of having been developed behind
corporate doors. But one large problem in particular was that it was not corporate doors. But one large problem in particular was that it was not
designed to work on multiprocessor systems. Before this networking stack designed to work on multiprocessor systems. Before this networking stack
(now called mac80211) could be merged, a locking scheme needed to be (now called mac80211) could be merged, a locking scheme needed to be
retrofitted onto it. retrofitted onto it.
Once upon a time, Linux kernel code could be developed without thinking Once upon a time, Linux kernel code could be developed without thinking
about the concurrency issues presented by multiprocessor systems. Now, about the concurrency issues presented by multiprocessor systems. Now,
...@@ -169,7 +178,8 @@ enough to pick the right tool for the job. Code which shows a lack of ...@@ -169,7 +178,8 @@ enough to pick the right tool for the job. Code which shows a lack of
attention to concurrency will have a difficult path into the mainline. attention to concurrency will have a difficult path into the mainline.
* Regressions Regressions
***********
One final hazard worth mentioning is this: it can be tempting to make a One final hazard worth mentioning is this: it can be tempting to make a
change (which may bring big improvements) which causes something to break change (which may bring big improvements) which causes something to break
...@@ -185,6 +195,8 @@ change if it brings new functionality to ten systems for each one it ...@@ -185,6 +195,8 @@ change if it brings new functionality to ten systems for each one it
breaks? The best answer to this question was expressed by Linus in July, breaks? The best answer to this question was expressed by Linus in July,
2007: 2007:
::
So we don't fix bugs by introducing new problems. That way lies So we don't fix bugs by introducing new problems. That way lies
madness, and nobody ever knows if you actually make any real madness, and nobody ever knows if you actually make any real
progress at all. Is it two steps forwards, one step back, or one progress at all. Is it two steps forwards, one step back, or one
...@@ -201,8 +213,8 @@ reason, a great deal of thought, clear documentation, and wide review for ...@@ -201,8 +213,8 @@ reason, a great deal of thought, clear documentation, and wide review for
user-space interfaces is always required. user-space interfaces is always required.
Code checking tools
4.2: CODE CHECKING TOOLS -------------------
For now, at least, the writing of error-free code remains an ideal that few For now, at least, the writing of error-free code remains an ideal that few
of us can reach. What we can hope to do, though, is to catch and fix as of us can reach. What we can hope to do, though, is to catch and fix as
...@@ -250,7 +262,7 @@ testing purposes. In particular, you should turn on: ...@@ -250,7 +262,7 @@ testing purposes. In particular, you should turn on:
There are quite a few other debugging options, some of which will be There are quite a few other debugging options, some of which will be
discussed below. Some of them have a significant performance impact and discussed below. Some of them have a significant performance impact and
should not be used all of the time. But some time spent learning the should not be used all of the time. But some time spent learning the
available options will likely be paid back many times over in short order. available options will likely be paid back many times over in short order.
One of the heavier debugging tools is the locking checker, or "lockdep." One of the heavier debugging tools is the locking checker, or "lockdep."
This tool will track the acquisition and release of every lock (spinlock or This tool will track the acquisition and release of every lock (spinlock or
...@@ -263,7 +275,7 @@ occasion, deadlock. This kind of problem can be painful (for both ...@@ -263,7 +275,7 @@ occasion, deadlock. This kind of problem can be painful (for both
developers and users) in a deployed system; lockdep allows them to be found developers and users) in a deployed system; lockdep allows them to be found
in an automated manner ahead of time. Code with any sort of non-trivial in an automated manner ahead of time. Code with any sort of non-trivial
locking should be run with lockdep enabled before being submitted for locking should be run with lockdep enabled before being submitted for
inclusion. inclusion.
As a diligent kernel programmer, you will, beyond doubt, check the return As a diligent kernel programmer, you will, beyond doubt, check the return
status of any operation (such as a memory allocation) which can fail. The status of any operation (such as a memory allocation) which can fail. The
...@@ -300,7 +312,7 @@ Documentation/coccinelle.txt for more information. ...@@ -300,7 +312,7 @@ Documentation/coccinelle.txt for more information.
Other kinds of portability errors are best found by compiling your code for Other kinds of portability errors are best found by compiling your code for
other architectures. If you do not happen to have an S/390 system or a other architectures. If you do not happen to have an S/390 system or a
Blackfin development board handy, you can still perform the compilation Blackfin development board handy, you can still perform the compilation
step. A large set of cross compilers for x86 systems can be found at step. A large set of cross compilers for x86 systems can be found at
http://www.kernel.org/pub/tools/crosstool/ http://www.kernel.org/pub/tools/crosstool/
...@@ -308,7 +320,8 @@ Some time spent installing and using these compilers will help avoid ...@@ -308,7 +320,8 @@ Some time spent installing and using these compilers will help avoid
embarrassment later. embarrassment later.
4.3: DOCUMENTATION Documentation
-------------
Documentation has often been more the exception than the rule with kernel Documentation has often been more the exception than the rule with kernel
development. Even so, adequate documentation will help to ease the merging development. Even so, adequate documentation will help to ease the merging
...@@ -364,7 +377,8 @@ out. Anything which might tempt a code janitor to make an incorrect ...@@ -364,7 +377,8 @@ out. Anything which might tempt a code janitor to make an incorrect
"cleanup" needs a comment saying why it is done the way it is. And so on. "cleanup" needs a comment saying why it is done the way it is. And so on.
4.4: INTERNAL API CHANGES Internal API changes
--------------------
The binary interface provided by the kernel to user space cannot be broken The binary interface provided by the kernel to user space cannot be broken
except under the most severe circumstances. The kernel's internal except under the most severe circumstances. The kernel's internal
......
5: POSTING PATCHES .. _development_posting:
Posting patches
===============
Sooner or later, the time comes when your work is ready to be presented to Sooner or later, the time comes when your work is ready to be presented to
the community for review and, eventually, inclusion into the mainline the community for review and, eventually, inclusion into the mainline
...@@ -11,7 +14,8 @@ SubmittingDrivers, and SubmitChecklist in the kernel documentation ...@@ -11,7 +14,8 @@ SubmittingDrivers, and SubmitChecklist in the kernel documentation
directory. directory.
5.1: WHEN TO POST When to post
------------
There is a constant temptation to avoid posting patches before they are There is a constant temptation to avoid posting patches before they are
completely "ready." For simple patches, that is not a problem. If the completely "ready." For simple patches, that is not a problem. If the
...@@ -27,7 +31,8 @@ patches which are known to be half-baked, but those who do will come in ...@@ -27,7 +31,8 @@ patches which are known to be half-baked, but those who do will come in
with the idea that they can help you drive the work in the right direction. with the idea that they can help you drive the work in the right direction.
5.2: BEFORE CREATING PATCHES Before creating patches
-----------------------
There are a number of things which should be done before you consider There are a number of things which should be done before you consider
sending patches to the development community. These include: sending patches to the development community. These include:
...@@ -52,7 +57,8 @@ As a general rule, putting in some extra thought before posting code almost ...@@ -52,7 +57,8 @@ As a general rule, putting in some extra thought before posting code almost
always pays back the effort in short order. always pays back the effort in short order.
5.3: PATCH PREPARATION Patch preparation
-----------------
The preparation of patches for posting can be a surprising amount of work, The preparation of patches for posting can be a surprising amount of work,
but, once again, attempting to save time here is not generally advisable but, once again, attempting to save time here is not generally advisable
...@@ -122,7 +128,8 @@ which takes quite a bit of time and thought after the "real work" has been ...@@ -122,7 +128,8 @@ which takes quite a bit of time and thought after the "real work" has been
done. When done properly, though, it is time well spent. done. When done properly, though, it is time well spent.
5.4: PATCH FORMATTING AND CHANGELOGS Patch formatting and changelogs
-------------------------------
So now you have a perfect series of patches for posting, but the work is So now you have a perfect series of patches for posting, but the work is
not done quite yet. Each patch needs to be formatted into a message which not done quite yet. Each patch needs to be formatted into a message which
...@@ -140,6 +147,8 @@ that end, each patch will be composed of the following: ...@@ -140,6 +147,8 @@ that end, each patch will be composed of the following:
subsystem name first, followed by the purpose of the patch. For subsystem name first, followed by the purpose of the patch. For
example: example:
::
gpio: fix build on CONFIG_GPIO_SYSFS=n gpio: fix build on CONFIG_GPIO_SYSFS=n
- A blank line followed by a detailed description of the contents of the - A blank line followed by a detailed description of the contents of the
...@@ -192,6 +201,8 @@ been associated with the development of this patch. They are described in ...@@ -192,6 +201,8 @@ been associated with the development of this patch. They are described in
detail in the SubmittingPatches document; what follows here is a brief detail in the SubmittingPatches document; what follows here is a brief
summary. Each of these lines has the format: summary. Each of these lines has the format:
::
tag: Full Name <email address> optional-other-stuff tag: Full Name <email address> optional-other-stuff
The tags in common use are: The tags in common use are:
...@@ -225,7 +236,8 @@ Be careful in the addition of tags to your patches: only Cc: is appropriate ...@@ -225,7 +236,8 @@ Be careful in the addition of tags to your patches: only Cc: is appropriate
for addition without the explicit permission of the person named. for addition without the explicit permission of the person named.
5.5: SENDING THE PATCH Sending the patch
-----------------
Before you mail your patches, there are a couple of other things you should Before you mail your patches, there are a couple of other things you should
take care of: take care of:
...@@ -287,6 +299,8 @@ obvious maintainer, Andrew Morton is often the patch target of last resort. ...@@ -287,6 +299,8 @@ obvious maintainer, Andrew Morton is often the patch target of last resort.
Patches need good subject lines. The canonical format for a patch line is Patches need good subject lines. The canonical format for a patch line is
something like: something like:
::
[PATCH nn/mm] subsys: one-line description of the patch [PATCH nn/mm] subsys: one-line description of the patch
where "nn" is the ordinal number of the patch, "mm" is the total number of where "nn" is the ordinal number of the patch, "mm" is the total number of
......
6: FOLLOWTHROUGH .. _development_followthrough:
Followthrough
=============
At this point, you have followed the guidelines given so far and, with the At this point, you have followed the guidelines given so far and, with the
addition of your own engineering skills, have posted a perfect series of addition of your own engineering skills, have posted a perfect series of
...@@ -16,7 +19,8 @@ standards. A failure to participate in this process is quite likely to ...@@ -16,7 +19,8 @@ standards. A failure to participate in this process is quite likely to
prevent the inclusion of your patches into the mainline. prevent the inclusion of your patches into the mainline.
6.1: WORKING WITH REVIEWERS Working with reviewers
----------------------
A patch of any significance will result in a number of comments from other A patch of any significance will result in a number of comments from other
developers as they review the code. Working with reviewers can be, for developers as they review the code. Working with reviewers can be, for
...@@ -97,7 +101,8 @@ though, and not before all other alternatives have been explored. And bear ...@@ -97,7 +101,8 @@ though, and not before all other alternatives have been explored. And bear
in mind, of course, that he may not agree with you either. in mind, of course, that he may not agree with you either.
6.2: WHAT HAPPENS NEXT What happens next
-----------------
If a patch is considered to be a good thing to add to the kernel, and once If a patch is considered to be a good thing to add to the kernel, and once
most of the review issues have been resolved, the next step is usually most of the review issues have been resolved, the next step is usually
...@@ -177,7 +182,8 @@ it with the assumption that you will not be around to maintain it ...@@ -177,7 +182,8 @@ it with the assumption that you will not be around to maintain it
afterward. afterward.
6.3: OTHER THINGS THAT CAN HAPPEN Other things that can happen
-----------------------------
One day, you may open your mail client and see that somebody has mailed you One day, you may open your mail client and see that somebody has mailed you
a patch to your code. That is one of the advantages of having your code a patch to your code. That is one of the advantages of having your code
......
7: ADVANCED TOPICS .. _development_advancedtopics:
Advanced topics
===============
At this point, hopefully, you have a handle on how the development process At this point, hopefully, you have a handle on how the development process
works. There is still more to learn, however! This section will cover a works. There is still more to learn, however! This section will cover a
number of topics which can be helpful for developers wanting to become a number of topics which can be helpful for developers wanting to become a
regular part of the Linux kernel development process. regular part of the Linux kernel development process.
7.1: MANAGING PATCHES WITH GIT Managing patches with git
-------------------------
The use of distributed version control for the kernel began in early 2002, The use of distributed version control for the kernel began in early 2002,
when Linus first started playing with the proprietary BitKeeper when Linus first started playing with the proprietary BitKeeper
...@@ -114,6 +118,8 @@ radar. Kernel developers tend to get unhappy when they see that kind of ...@@ -114,6 +118,8 @@ radar. Kernel developers tend to get unhappy when they see that kind of
thing happening; putting up a git tree with unreviewed or off-topic patches thing happening; putting up a git tree with unreviewed or off-topic patches
can affect your ability to get trees pulled in the future. Quoting Linus: can affect your ability to get trees pulled in the future. Quoting Linus:
::
You can send me patches, but for me to pull a git patch from you, I You can send me patches, but for me to pull a git patch from you, I
need to know that you know what you're doing, and I need to be able need to know that you know what you're doing, and I need to be able
to trust things *without* then having to go and check every to trust things *without* then having to go and check every
...@@ -141,7 +147,8 @@ format the request as other developers expect, and will also check to be ...@@ -141,7 +147,8 @@ format the request as other developers expect, and will also check to be
sure that you have remembered to push those changes to the public server. sure that you have remembered to push those changes to the public server.
7.2: REVIEWING PATCHES Reviewing patches
-----------------
Some readers will certainly object to putting this section with "advanced Some readers will certainly object to putting this section with "advanced
topics" on the grounds that even beginning kernel developers should be topics" on the grounds that even beginning kernel developers should be
......
8: FOR MORE INFORMATION .. _development_conclusion:
For more information
====================
There are numerous sources of information on Linux kernel development and There are numerous sources of information on Linux kernel development and
related topics. First among those will always be the Documentation related topics. First among those will always be the Documentation
...@@ -47,7 +50,8 @@ Documentation for git can be found at: ...@@ -47,7 +50,8 @@ Documentation for git can be found at:
http://www.kernel.org/pub/software/scm/git/docs/user-manual.html http://www.kernel.org/pub/software/scm/git/docs/user-manual.html
9: CONCLUSION Conclusion
==========
Congratulations to anybody who has made it through this long-winded Congratulations to anybody who has made it through this long-winded
document. Hopefully it has provided a helpful understanding of how the document. Hopefully it has provided a helpful understanding of how the
......
A guide to the Kernel Development Process
=========================================
Contents:
.. toctree::
:numbered:
:maxdepth: 2
1.Intro
2.Process
3.Early-stage
4.Coding
5.Posting
6.Followthrough
7.AdvancedTopics
8.Conclusion
The purpose of this document is to help developers (and their managers)
work with the development community with a minimum of frustration. It is
an attempt to document how this community works in a way which is
accessible to those who are not intimately familiar with Linux kernel
development (or, indeed, free software development in general). While
there is some technical material here, this is very much a process-oriented
discussion which does not require a deep knowledge of kernel programming to
understand.
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment