docs: update the development process document

Here's a set of changes updating Documentation/development-process. I have update kernel releases and relevant statistics, added information for a couple of tools, zapped some trailing white space, and generally tried to make it more closely match the current state of affairs. [Typo fixes from Joe Perches and Nicolas Kaiser incorporated] Signed-off-by: Jonathan Corbet <corbet@lwn.net> Acked-by: Greg KH <greg@kroah.com> Cc: Randy Dunlap <rdunlap@xenotime.net>

docs: update the development process document
Here's a set of changes updating Documentation/development-process. I have update kernel releases and relevant statistics, added information for a couple of tools, zapped some trailing white space, and generally tried to make it more closely match the current state of affairs. [Typo fixes from Joe Perches and Nicolas Kaiser incorporated] Signed-off-by: Jonathan Corbet <corbet@lwn.net> Acked-by: Greg KH <greg@kroah.com> Cc: Randy Dunlap <rdunlap@xenotime.net>
Jonathan Corbet
1 parent 9cad796270
Showing 7 changed files with 167 additions and 128 deletions Side-by-side Diff
Documentation/development-process/1.Intro
Documentation/development-process/2.Process
Documentation/development-process/3.Early-stage
Documentation/development-process/4.Coding
Documentation/development-process/5.Posting
Documentation/development-process/6.Followthrough
Documentation/development-process/7.AdvancedTopics
@@ -56,13 +56,13 @@
  
 1.2: WHAT THIS DOCUMENT IS ABOUT
  
-The Linux kernel, at over 6 million lines of code and well over 1000 active
-contributors, is one of the largest and most active free software projects
-in existence.  Since its humble beginning in 1991, this kernel has evolved
-into a best-of-breed operating system component which runs on pocket-sized
-digital music players, desktop PCs, the largest supercomputers in
-existence, and all types of systems in between.  It is a robust, efficient,
-and scalable solution for almost any situation.
+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
+software projects in existence.  Since its humble beginning in 1991, this
+kernel has evolved into a best-of-breed operating system component which
+runs on pocket-sized digital music players, desktop PCs, the largest
+supercomputers in existence, and all types of systems in between.  It is a
+robust, 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.  Hardware
@@ -115,7 +115,7 @@
 improved by comments from Johannes Berg, James Berry, Alex Chiang, Roland
 Dreier, Randy Dunlap, Jake Edge, Jiri Kosina, Matt Mackall, Arthur Marsh,
 Amanda McPherson, Andrew Morton, Andrew Price, Tsugikazu Shibata, and
-Jochen Voß. 
+Jochen Voß.
  
 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.
@@ -221,7 +221,7 @@
 - Everything that was said above about code review applies doubly to
   closed-source code.  Since this code is not available at all, it cannot
   have been reviewed by the community and will, beyond doubt, have serious
-  problems. 
+  problems.
  
 Makers of embedded systems, in particular, may be tempted to disregard much
 of what has been said in this section in the belief that they are shipping
@@ -14,16 +14,15 @@
 major kernel release happening every two or three months.  The recent
 release history looks like this:
  
-	2.6.26	July 13, 2008
-	2.6.25	April 16, 2008
-	2.6.24	January 24, 2008
-	2.6.23	October 9, 2007
-	2.6.22	July 8, 2007
-	2.6.21	April 25, 2007
-	2.6.20	February 4, 2007
+	2.6.38	March 14, 2011
+	2.6.37	January 4, 2011
+	2.6.36	October 20, 2010
+	2.6.35	August 1, 2010
+	2.6.34	May 15, 2010
+	2.6.33	February 24, 2010
  
 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 over 10,000
+API changes, and more.  A typical 2.6 release can contain nearly 10,000
 changesets with changes to several hundred thousand lines of code.  2.6 is
 thus the leading edge of Linux kernel development; the kernel uses a
 rolling development model which is continually integrating major changes.
@@ -42,13 +41,13 @@
 and staged ahead of time.  How that process works will be described in
 detail later on).
  
-The merge window lasts for two weeks.  At the end of this time, Linus
-Torvalds will declare that the window is closed and release the first of
-the "rc" kernels.  For the kernel which is destined to be 2.6.26, for
-example, the release which happens at the end of the merge window will be
-called 2.6.26-rc1.  The -rc1 release is the signal that the time to merge
-new features has passed, and that the time to stabilize the next kernel has
-begun.
+The merge window lasts for approximately two weeks.  At the end of this
+time, Linus Torvalds will declare that the window is closed and release the
+first of the "rc" kernels.  For the kernel which is destined to be 2.6.40,
+for example, the release which happens at the end of the merge window will
+be called 2.6.40-rc1.  The -rc1 release is the signal that the time to
+merge new features has passed, and that the time to stabilize the next
+kernel has begun.
  
 Over the next six to ten weeks, only patches which fix problems should be
 submitted to the mainline.  On occasion a more significant change will be
  
@@ -66,20 +65,19 @@
 considered to be sufficiently stable and the final 2.6.x release is made.
 At that point the whole process starts over again.
  
-As an example, here is how the 2.6.25 development cycle went (all dates in
-2008): 
+As an example, here is how the 2.6.38 development cycle went (all dates in
+2011):
  
-	January 24	2.6.24 stable release
-	February 10	2.6.25-rc1, merge window closes
-	February 15	2.6.25-rc2
-	February 24	2.6.25-rc3
-	March 4	 	2.6.25-rc4
-	March 9		2.6.25-rc5
-	March 16	2.6.25-rc6
-	March 25	2.6.25-rc7
-	April 1		2.6.25-rc8
-	April 11	2.6.25-rc9
-	April 16	2.6.25 stable release
+	January 4	2.6.37 stable release
+	January 18	2.6.38-rc1, merge window closes
+	January 21	2.6.38-rc2
+	February 1	2.6.38-rc3
+	February 7	2.6.38-rc4
+	February 15	2.6.38-rc5
+	February 21	2.6.38-rc6
+	March 1		2.6.38-rc7
+	March 7		2.6.38-rc8
+	March 14	2.6.38 stable release
  
 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
@@ -87,7 +85,7 @@
 break systems which worked in the past are considered to be especially
 serious.  For this reason, patches which cause regressions are looked upon
 unfavorably and are quite likely to be reverted during the stabilization
-period. 
+period.
  
 The developers' goal is to fix all known regressions before the stable
 release is made.  In the real world, this kind of perfection is hard to
  
  
  
  
@@ -99,28 +97,36 @@
 of them are serious.
  
 Once a stable release is made, its ongoing maintenance is passed off to the
-"stable team," currently comprised of Greg Kroah-Hartman and Chris Wright.
-The stable team will release occasional updates to the stable release using
-the 2.6.x.y numbering scheme.  To be considered for an update release, a
-patch must (1) fix a significant bug, and (2) already be merged into the
-mainline for the next development kernel.  Continuing our 2.6.25 example,
-the history (as of this writing) is:
+"stable team," currently consisting of Greg Kroah-Hartman.  The stable team
+will release occasional updates to the stable release using the 2.6.x.y
+numbering scheme.  To be considered for an update release, a patch must (1)
+fix a significant bug, and (2) already be merged into the mainline for the
+next development kernel.  Kernels will typically receive stable updates for
+a little more than one development cycle past their initial release.  So,
+for example, the 2.6.36 kernel's history looked like:
  
-	May 1		2.6.25.1
-	May 6		2.6.25.2 
-	May 9		2.6.25.3 
-	May 15		2.6.25.4
-	June 7		2.6.25.5
-	June 9		2.6.25.6
-	June 16		2.6.25.7
-	June 21		2.6.25.8
-	June 24		2.6.25.9
+	October 10	2.6.36 stable release
+	November 22	2.6.36.1
+	December 9	2.6.36.2
+	January 7	2.6.36.3
+	February 17	2.6.36.4
  
-Stable updates for a given kernel are made for approximately six months;
-after that, the maintenance of stable releases is solely the responsibility
-of the distributors which have shipped that particular kernel.
+2.6.36.4 was the final stable update for the 2.6.36 release.
  
+Some kernels are designated "long term" kernels; they will receive support
+for a longer period.  As of this writing, the current long term kernels
+and their maintainers are:
  
+	2.6.27	Willy Tarreau		(Deep-frozen stable kernel)
+	2.6.32	Greg Kroah-Hartman
+	2.6.35	Andi Kleen		(Embedded flag kernel)
+
+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
+are no known plans for long-term support for any specific upcoming
+release.
+
+
 2.2: THE LIFECYCLE OF A PATCH
  
 Patches do not go directly from the developer's keyboard into the mainline
@@ -130,7 +136,7 @@
 This process can happen quickly for minor fixes, or, in the case of large
 and controversial changes, go on for years.  Much developer frustration
 comes from a lack of understanding of this process or from attempts to
-circumvent it.  
+circumvent it.
  
 In the hopes of reducing that frustration, this document will describe how
 a patch gets into the kernel.  What follows below is an introduction which
@@ -193,8 +199,8 @@
 2.3: HOW PATCHES GET INTO THE KERNEL
  
 There is exactly one person who can merge patches into the mainline kernel
-repository: Linus Torvalds.  But, of the over 12,000 patches which went
-into the 2.6.25 kernel, only 250 (around 2%) were directly chosen by Linus
+repository: Linus Torvalds.  But, of the over 9,500 patches which went
+into the 2.6.38 kernel, only 112 (around 1.3%) were directly chosen by Linus
 himself.  The kernel project has long since grown to a size where no single
 developer could possibly inspect and select every patch unassisted.  The
 way the kernel developers have addressed this growth is through the use of
@@ -229,7 +235,7 @@
 etc.  This chain of repositories can be arbitrarily long, though it rarely
 exceeds two or three links.  Since each maintainer in the chain trusts
 those managing lower-level trees, this process is known as the "chain of
-trust." 
+trust."
  
 Clearly, in a system like this, getting patches into the kernel depends on
 finding the right maintainer.  Sending patches directly to Linus is not
@@ -254,7 +260,7 @@
 collected for testing and review.  The older of these trees, maintained by
 Andrew Morton, is called "-mm" (for memory management, which is how it got
 started).  The -mm tree integrates patches from a long list of subsystem
-trees; it also has some patches aimed at helping with debugging.  
+trees; it also has some patches aimed at helping with debugging.
  
 Beyond that, -mm contains a significant collection of patches which have
 been selected by Andrew directly.  These patches may have been posted on a
@@ -264,8 +270,8 @@
 patch into the mainline, it is likely to end up in -mm.  Miscellaneous
 patches which accumulate in -mm will eventually either be forwarded on to
 an appropriate subsystem tree or be sent directly to Linus.  In a typical
-development cycle, approximately 10% of the patches going into the mainline
-get there via -mm.
+development cycle, approximately 5-10% of the patches going into the
+mainline get there via -mm.
  
 The current -mm patch is available in the "mmotm" (-mm of the moment)
 directory at:
@@ -275,7 +281,7 @@
 Use of the MMOTM tree is likely to be a frustrating experience, though;
 there is a definite chance that it will not even compile.
  
-The other -next tree, started more recently, is linux-next, maintained by
+The primary tree for next-cycle patch merging is linux-next, maintained by
 Stephen Rothwell.  The linux-next tree is, by design, a snapshot of what
 the mainline is expected to look like after the next merge window closes.
 Linux-next trees are announced on the linux-kernel and linux-next mailing
  
  
@@ -287,25 +293,14 @@
  
 	http://linux.f-seidel.de/linux-next/pmwiki/
  
-How the linux-next tree will fit into the development process is still
-changing.  As of this writing, the first full development cycle involving
-linux-next (2.6.26) is coming to an end; thus far, it has proved to be a
-valuable resource for finding and fixing integration problems before the
-beginning of the merge window.  See http://lwn.net/Articles/287155/ for
-more information on how linux-next has worked to set up the 2.6.27 merge
-window.
+Linux-next has become an integral part of the kernel development process;
+all patches merged during a given merge window should really have found
+their way into linux-next some time before the merge window opens.
  
-Some developers have begun to suggest that linux-next should be used as the
-target for future development as well.  The linux-next tree does tend to be
-far ahead of the mainline and is more representative of the tree into which
-any new work will be merged.  The downside to this idea is that the
-volatility of linux-next tends to make it a difficult development target.
-See http://lwn.net/Articles/289013/ for more information on this topic, and
-stay tuned; much is still in flux where linux-next is involved.
  
 2.4.1: STAGING TREES
  
-The kernel source tree now 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
 being added to the kernel tree live.  They remain in drivers/staging while
 they still need more work; once complete, they can be moved into the
  
@@ -313,16 +308,24 @@
 up to Linux kernel coding or quality standards, but people may want to use
 them and track development.
  
-Greg Kroah-Hartman currently (as of 2.6.36) maintains the staging tree.
-Drivers that still need work are sent to him, with each driver having
-its own subdirectory in drivers/staging/.  Along with the driver source
-files, a TODO file should be present in the directory as well.  The TODO
-file lists the pending work that the driver needs for acceptance into
-the kernel proper, as well as a list of people that should be Cc'd for any
-patches to the driver.  Staging drivers that don't currently build should
-have their config entries depend upon CONFIG_BROKEN.  Once they can
-be successfully built without outside patches, CONFIG_BROKEN can be removed.
+Greg Kroah-Hartman currently maintains the staging tree.  Drivers that
+still need work are sent to him, with each driver having its own
+subdirectory in drivers/staging/.  Along with the driver source files, a
+TODO file should be present in the directory as well.  The TODO file lists
+the pending work that the driver needs for acceptance into the kernel
+proper, as well as a list of people that should be Cc'd for any patches to
+the driver.  Current rules require that drivers contributed to staging
+must, at a minimum, compile properly.
  
+Staging can be a relatively easy way to get new drivers into the mainline
+where, with luck, they will come to the attention of other developers and
+improve quickly.  Entry into staging is not the end of the story, though;
+code in staging which is not seeing regular progress will eventually be
+removed.  Distributors also tend to be relatively reluctant to enable
+staging drivers.  So staging is, at best, a stop on the way toward becoming
+a proper mainline driver.
+
+
 2.5: TOOLS
  
 As can be seen from the above text, the kernel development process depends
  
@@ -347,12 +350,8 @@
  
 	http://git-scm.com/
  
-That page has pointers to documentation and tutorials.  One should be
-aware, in particular, of the Kernel Hacker's Guide to git, which has
-information specific to kernel development:
+That page has pointers to documentation and tutorials.
  
-	http://linux.yyz.us/git-howto.html
-
 Among the kernel developers who do not use git, the most popular choice is
 almost certainly Mercurial:
  
@@ -408,7 +407,7 @@
   important to filter on both the topic of interest (though note that
   long-running conversations can drift away from the original subject
   without changing the email subject line) and the people who are
-  participating.  
+  participating.
  
 - Do not feed the trolls.  If somebody is trying to stir up an angry
   response, ignore them.
@@ -110,8 +110,8 @@
  
  - The AppArmor security module made use of internal virtual filesystem
    data structures in ways which were considered to be unsafe and
-   unreliable.  This code has since been significantly reworked, but
-   remains outside of the mainline.
+   unreliable.  This concern (among others) kept AppArmor out of the
+   mainline for years.
  
 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.
@@ -138,6 +138,19 @@
 patches.  Those are the people who will be best placed to help with a new
 development project.
  
+The task of finding the right maintainer is sometimes challenging enough
+that the kernel developers have added a script to ease the process:
+
+	.../scripts/get_maintainer.pl
+
+This script will return the current maintainer(s) for a given file or
+directory when given the "-f" option.  If passed a patch on the
+command line, it will list the maintainers who should probably receive
+copies of the patch.  There are a number of options regulating how hard
+get_maintainer.pl will search for maintainers; please be careful about
+using the more aggressive options as you may end up including developers
+who have no real interest in the code you are modifying.
+
 If all else fails, talking to Andrew Morton can be an effective way to
 track down a maintainer for a specific piece of code.
  
@@ -155,11 +168,15 @@
 matter is (1) kernel developers tend to be busy, (2) there is no shortage
 of people with grand plans and little code (or even prospect of code) to
 back them up, and (3) nobody is obligated to review or comment on ideas
-posted by others.  If a request-for-comments posting yields little in the
-way of comments, do not assume that it means there is no interest in the
-project.  Unfortunately, you also cannot assume that there are no problems
-with your idea.  The best thing to do in this situation is to proceed,
-keeping the community informed as you go.
+posted by others.  Beyond that, high-level designs often hide problems
+which are only reviewed when somebody actually tries to implement those
+designs; for that reason, kernel developers would rather see the code.
+
+If a request-for-comments posting yields little in the way of comments, do
+not assume that it means there is no interest in the project.
+Unfortunately, you also cannot assume that there are no problems with your
+idea.  The best thing to do in this situation is to proceed, keeping the
+community informed as you go.
  
  
 3.5: GETTING OFFICIAL BUY-IN
@@ -131,7 +131,12 @@
 often does not apply to contemporary hardware.  Space *is* time, in that a
 larger program will run slower than one which is more compact.
  
+More recent compilers take an increasingly active role in deciding whether
+a given function should actually be inlined or not.  So the liberal
+placement of "inline" keywords may not just be excessive; it could also be
+irrelevant.
  
+
 * Locking
  
 In May, 2006, the "Devicescape" networking stack was, with great
@@ -285,6 +290,13 @@
 distributor does not package it); it can then be run on the code by adding
 "C=1" to your make command.
  
+The "Coccinelle" tool (http://coccinelle.lip6.fr/) is able to find a wide
+variety of potential coding problems; it can also propose fixes for those
+problems.  Quite a few "semantic patches" for the kernel have been packaged
+under the scripts/coccinelle directory; running "make coccicheck" will run
+through those semantic patches and report on any problems found.  See
+Documentation/coccinelle.txt for more information.
+
 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
 Blackfin development board handy, you can still perform the compilation
@@ -308,7 +320,9 @@
 changelog.  Log entries should describe the problem being solved, the form
 of the solution, the people who worked on the patch, any relevant
 effects on performance, and anything else that might be needed to
-understand the patch.
+understand the patch.  Be sure that the changelog says *why* the patch is
+worth applying; a surprising number of developers fail to provide that
+information.
  
 Any code which adds a new user-space interface - including new sysfs or
 /proc files - should include documentation of that interface which enables
@@ -321,7 +335,7 @@
 appropriate entries to this file.
  
 Any new configuration options must be accompanied by help text which
-clearly explains the options and when the user might want to select them. 
+clearly explains the options and when the user might want to select them.
  
 Internal API information for many subsystems is documented by way of
 specially-formatted comments; these comments can be extracted and formatted
@@ -372,7 +386,8 @@
 lead to literally hundreds or thousands of changes - many of which are
 likely to conflict with work being done by other developers.  Needless to
 say, this can be a large job, so it is best to be sure that the
-justification is solid.
+justification is solid.  Note that the Coccinelle tool can help with
+wide-ranging API changes.
  
 When making an incompatible API change, one should, whenever possible,
 ensure that code which has not been updated is caught by the compiler.
@@ -60,13 +60,16 @@
  
 Patches must be prepared against a specific version of the kernel.  As a
 general rule, a patch should be based on the current mainline as found in
-Linus's git tree.  It may become necessary to make versions against -mm,
-linux-next, or a subsystem tree, though, to facilitate wider testing and
-review.  Depending on the area of your patch and what is going on
-elsewhere, basing a patch against these other trees can require a
-significant amount of work resolving conflicts and dealing with API
-changes.
+Linus's git tree.  When basing on mainline, start with a well-known release
+point - a stable or -rc release - rather than branching off the mainline at
+an arbitrary spot.
  
+It may become necessary to make versions against -mm, linux-next, or a
+subsystem tree, though, to facilitate wider testing and review.  Depending
+on the area of your patch and what is going on elsewhere, basing a patch
+against these other trees can require a significant amount of work
+resolving conflicts and dealing with API changes.
+
 Only the most simple changes should be formatted as a single patch;
 everything else should be made as a logical series of changes.  Splitting
 up patches is a bit of an art; some developers spend a long time figuring
  
@@ -100,11 +103,11 @@
    result is a broken kernel, you will make life harder for developers and
    users who are engaging in the noble work of tracking down problems.
  
- - Do not overdo it, though.  One developer recently posted a set of edits
+ - Do not overdo it, though.  One developer once posted a set of edits
    to a single file as 500 separate patches - an act which did not make him
    the most popular person on the kernel mailing list.  A single patch can
    be reasonably large as long as it still contains a single *logical*
-   change. 
+   change.
  
  - It can be tempting to add a whole new infrastructure with a series of
    patches, but to leave that infrastructure unused until the final patch
@@ -162,7 +165,8 @@
 for the change as well as possible given the one-line constraint.  The
 detailed description can then amplify on those topics and provide any
 needed additional information.  If the patch fixes a bug, cite the commit
-which introduced the bug if possible.  If a problem is associated with
+which introduced the bug if possible (and please provide both the commit ID
+and the title when citing commits).  If a problem is associated with
 specific log or compiler output, include that output to help others
 searching for a solution to the same problem.  If the change is meant to
 support other changes coming in later patch, say so.  If internal APIs are
@@ -230,7 +234,7 @@
    which have had gratuitous white-space changes or line wrapping performed
    by the mail client will not apply at the other end, and often will not
    be examined in any detail.  If there is any doubt at all, mail the patch
-   to yourself and convince yourself that it shows up intact.  
+   to yourself and convince yourself that it shows up intact.
  
    Documentation/email-clients.txt has some helpful hints on making
    specific mail clients work for sending patches.
@@ -287,7 +291,7 @@
  
 where "nn" is the ordinal number of the patch, "mm" is the total number of
 patches in the series, and "subsys" is the name of the affected subsystem.
-Clearly, nn/mm can be omitted for a single, standalone patch.  
+Clearly, nn/mm can be omitted for a single, standalone patch.
  
 If you have a significant series of patches, it is customary to send an
 introductory description as part zero.  This convention is not universally
@@ -299,6 +303,6 @@
 sent as a reply to the first part so that they all thread together at the
 receiving end.  Tools like git and quilt have commands to mail out a set of
 patches with the proper threading.  If you have a long series, though, and
-are using git, please provide the --no-chain-reply-to option to avoid
+are using git, please stay away from the --chain-reply-to option to avoid
 creating exceptionally deep nesting.
@@ -66,6 +66,11 @@
 that you don't realize that something is fundamentally wrong or, perhaps,
 you're not even solving the right problem.
  
+Andrew Morton has suggested that every review comment which does not result
+in a code change should result in an additional code comment instead; that
+can help future reviewers avoid the questions which came up the first time
+around.
+
 One fatal mistake is to ignore review comments in the hope that they will
 go away.  They will not go away.  If you repost code without having
 responded to the comments you got the time before, you're likely to find
@@ -100,7 +105,7 @@
 subsystem to the next; each maintainer has his or her own way of doing
 things.  In particular, there may be more than one tree - one, perhaps,
 dedicated to patches planned for the next merge window, and another for
-longer-term work.  
+longer-term work.
  
 For patches applying to areas for which there is no obvious subsystem tree
 (memory management patches, for example), the default tree often ends up
@@ -109,11 +114,10 @@
  
 Inclusion into a subsystem tree can bring a higher level of visibility to a
 patch.  Now other developers working with that tree will get the patch by
-default.  Subsystem trees typically feed into -mm and linux-next as well,
-making their contents visible to the development community as a whole.  At
-this point, there's a good chance that you will get more comments from a
-new set of reviewers; these comments need to be answered as in the previous
-round.
+default.  Subsystem trees typically feed linux-next as well, making their
+contents visible to the development community as a whole.  At this point,
+there's a good chance that you will get more comments from a new set of
+reviewers; these comments need to be answered as in the previous round.
  
 What may also happen at this point, depending on the nature of your patch,
 is that conflicts with work being done by others turn up.  In the worst
@@ -119,7 +119,7 @@
 	to trust things *without* then having to go and check every
 	individual change by hand.
  
-(http://lwn.net/Articles/224135/).  
+(http://lwn.net/Articles/224135/).
  
 To avoid this kind of situation, ensure that all patches within a given
 branch stick closely to the associated topic; a "driver fixes" branch
@@ -138,7 +138,7 @@
 your tree is, what branch to pull, and what changes will result from the
 pull.  The git request-pull command can be helpful in this regard; it will
 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
...	...	@@ -56,13 +56,13 @@
56	56
57	57	1.2: WHAT THIS DOCUMENT IS ABOUT
58	58
59		-The Linux kernel, at over 6 million lines of code and well over 1000 active
60		-contributors, is one of the largest and most active free software projects
61		-in existence. Since its humble beginning in 1991, this kernel has evolved
62		-into a best-of-breed operating system component which runs on pocket-sized
63		-digital music players, desktop PCs, the largest supercomputers in
64		-existence, and all types of systems in between. It is a robust, efficient,
65		-and scalable solution for almost any situation.
	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	66
67	67	With the growth of Linux has come an increase in the number of developers
68	68	(and companies) wishing to participate in its development. Hardware
...	...	@@ -115,7 +115,7 @@
115	115	improved by comments from Johannes Berg, James Berry, Alex Chiang, Roland
116	116	Dreier, Randy Dunlap, Jake Edge, Jiri Kosina, Matt Mackall, Arthur Marsh,
117	117	Amanda McPherson, Andrew Morton, Andrew Price, Tsugikazu Shibata, and
118		-Jochen Voß.
	118	+Jochen Voß.
119	119
120	120	This work was supported by the Linux Foundation; thanks especially to
121	121	Amanda McPherson, who saw the value of this effort and made it all happen.
...	...	@@ -221,7 +221,7 @@
221	221	- Everything that was said above about code review applies doubly to
222	222	closed-source code. Since this code is not available at all, it cannot
223	223	have been reviewed by the community and will, beyond doubt, have serious
224		- problems.
	224	+ problems.
225	225
226	226	Makers of embedded systems, in particular, may be tempted to disregard much
227	227	of what has been said in this section in the belief that they are shipping
...	...	@@ -14,16 +14,15 @@
14	14	major kernel release happening every two or three months. The recent
15	15	release history looks like this:
16	16
17		- 2.6.26 July 13, 2008
18		- 2.6.25 April 16, 2008
19		- 2.6.24 January 24, 2008
20		- 2.6.23 October 9, 2007
21		- 2.6.22 July 8, 2007
22		- 2.6.21 April 25, 2007
23		- 2.6.20 February 4, 2007
	17	+ 2.6.38 March 14, 2011
	18	+ 2.6.37 January 4, 2011
	19	+ 2.6.36 October 20, 2010
	20	+ 2.6.35 August 1, 2010
	21	+ 2.6.34 May 15, 2010
	22	+ 2.6.33 February 24, 2010
24	23
25	24	Every 2.6.x release is a major kernel release with new features, internal
26		-API changes, and more. A typical 2.6 release can contain over 10,000
	25	+API changes, and more. A typical 2.6 release can contain nearly 10,000
27	26	changesets with changes to several hundred thousand lines of code. 2.6 is
28	27	thus the leading edge of Linux kernel development; the kernel uses a
29	28	rolling development model which is continually integrating major changes.
...	...	@@ -42,13 +41,13 @@
42	41	and staged ahead of time. How that process works will be described in
43	42	detail later on).
44	43
45		-The merge window lasts for two weeks. At the end of this time, Linus
46		-Torvalds will declare that the window is closed and release the first of
47		-the "rc" kernels. For the kernel which is destined to be 2.6.26, for
48		-example, the release which happens at the end of the merge window will be
49		-called 2.6.26-rc1. The -rc1 release is the signal that the time to merge
50		-new features has passed, and that the time to stabilize the next kernel has
51		-begun.
	44	+The merge window lasts for approximately two weeks. At the end of this
	45	+time, Linus Torvalds will declare that the window is closed and release the
	46	+first of the "rc" kernels. For the kernel which is destined to be 2.6.40,
	47	+for example, the release which happens at the end of the merge window will
	48	+be called 2.6.40-rc1. The -rc1 release is the signal that the time to
	49	+merge new features has passed, and that the time to stabilize the next
	50	+kernel has begun.
52	51
53	52	Over the next six to ten weeks, only patches which fix problems should be
54	53	submitted to the mainline. On occasion a more significant change will be
55	54
...	...	@@ -66,20 +65,19 @@
66	65	considered to be sufficiently stable and the final 2.6.x release is made.
67	66	At that point the whole process starts over again.
68	67
69		-As an example, here is how the 2.6.25 development cycle went (all dates in
70		-2008):
	68	+As an example, here is how the 2.6.38 development cycle went (all dates in
	69	+2011):
71	70
72		- January 24 2.6.24 stable release
73		- February 10 2.6.25-rc1, merge window closes
74		- February 15 2.6.25-rc2
75		- February 24 2.6.25-rc3
76		- March 4 2.6.25-rc4
77		- March 9 2.6.25-rc5
78		- March 16 2.6.25-rc6
79		- March 25 2.6.25-rc7
80		- April 1 2.6.25-rc8
81		- April 11 2.6.25-rc9
82		- April 16 2.6.25 stable release
	71	+ January 4 2.6.37 stable release
	72	+ January 18 2.6.38-rc1, merge window closes
	73	+ January 21 2.6.38-rc2
	74	+ February 1 2.6.38-rc3
	75	+ February 7 2.6.38-rc4
	76	+ February 15 2.6.38-rc5
	77	+ February 21 2.6.38-rc6
	78	+ March 1 2.6.38-rc7
	79	+ March 7 2.6.38-rc8
	80	+ March 14 2.6.38 stable release
83	81
84	82	How do the developers decide when to close the development cycle and create
85	83	the stable release? The most significant metric used is the list of
...	...	@@ -87,7 +85,7 @@
87	85	break systems which worked in the past are considered to be especially
88	86	serious. For this reason, patches which cause regressions are looked upon
89	87	unfavorably and are quite likely to be reverted during the stabilization
90		-period.
	88	+period.
91	89
92	90	The developers' goal is to fix all known regressions before the stable
93	91	release is made. In the real world, this kind of perfection is hard to
94	92
95	93
96	94
97	95
...	...	@@ -99,28 +97,36 @@
99	97	of them are serious.
100	98
101	99	Once a stable release is made, its ongoing maintenance is passed off to the
102		-"stable team," currently comprised of Greg Kroah-Hartman and Chris Wright.
103		-The stable team will release occasional updates to the stable release using
104		-the 2.6.x.y numbering scheme. To be considered for an update release, a
105		-patch must (1) fix a significant bug, and (2) already be merged into the
106		-mainline for the next development kernel. Continuing our 2.6.25 example,
107		-the history (as of this writing) is:
	100	+"stable team," currently consisting of Greg Kroah-Hartman. The stable team
	101	+will release occasional updates to the stable release using the 2.6.x.y
	102	+numbering scheme. To be considered for an update release, a patch must (1)
	103	+fix a significant bug, and (2) already be merged into the mainline for the
	104	+next development kernel. Kernels will typically receive stable updates for
	105	+a little more than one development cycle past their initial release. So,
	106	+for example, the 2.6.36 kernel's history looked like:
108	107
109		- May 1 2.6.25.1
110		- May 6 2.6.25.2
111		- May 9 2.6.25.3
112		- May 15 2.6.25.4
113		- June 7 2.6.25.5
114		- June 9 2.6.25.6
115		- June 16 2.6.25.7
116		- June 21 2.6.25.8
117		- June 24 2.6.25.9
	108	+ October 10 2.6.36 stable release
	109	+ November 22 2.6.36.1
	110	+ December 9 2.6.36.2
	111	+ January 7 2.6.36.3
	112	+ February 17 2.6.36.4
118	113
119		-Stable updates for a given kernel are made for approximately six months;
120		-after that, the maintenance of stable releases is solely the responsibility
121		-of the distributors which have shipped that particular kernel.
	114	+2.6.36.4 was the final stable update for the 2.6.36 release.
122	115
	116	+Some kernels are designated "long term" kernels; they will receive support
	117	+for a longer period. As of this writing, the current long term kernels
	118	+and their maintainers are:
123	119
	120	+ 2.6.27 Willy Tarreau (Deep-frozen stable kernel)
	121	+ 2.6.32 Greg Kroah-Hartman
	122	+ 2.6.35 Andi Kleen (Embedded flag kernel)
	123	+
	124	+The selection of a kernel for long-term support is purely a matter of a
	125	+maintainer having the need and the time to maintain that release. There
	126	+are no known plans for long-term support for any specific upcoming
	127	+release.
	128	+
	129	+
124	130	2.2: THE LIFECYCLE OF A PATCH
125	131
126	132	Patches do not go directly from the developer's keyboard into the mainline
...	...	@@ -130,7 +136,7 @@
130	136	This process can happen quickly for minor fixes, or, in the case of large
131	137	and controversial changes, go on for years. Much developer frustration
132	138	comes from a lack of understanding of this process or from attempts to
133		-circumvent it.
	139	+circumvent it.
134	140
135	141	In the hopes of reducing that frustration, this document will describe how
136	142	a patch gets into the kernel. What follows below is an introduction which
...	...	@@ -193,8 +199,8 @@
193	199	2.3: HOW PATCHES GET INTO THE KERNEL
194	200
195	201	There is exactly one person who can merge patches into the mainline kernel
196		-repository: Linus Torvalds. But, of the over 12,000 patches which went
197		-into the 2.6.25 kernel, only 250 (around 2%) were directly chosen by Linus
	202	+repository: Linus Torvalds. But, of the over 9,500 patches which went
	203	+into the 2.6.38 kernel, only 112 (around 1.3%) were directly chosen by Linus
198	204	himself. The kernel project has long since grown to a size where no single
199	205	developer could possibly inspect and select every patch unassisted. The
200	206	way the kernel developers have addressed this growth is through the use of
...	...	@@ -229,7 +235,7 @@
229	235	etc. This chain of repositories can be arbitrarily long, though it rarely
230	236	exceeds two or three links. Since each maintainer in the chain trusts
231	237	those managing lower-level trees, this process is known as the "chain of
232		-trust."
	238	+trust."
233	239
234	240	Clearly, in a system like this, getting patches into the kernel depends on
235	241	finding the right maintainer. Sending patches directly to Linus is not
...	...	@@ -254,7 +260,7 @@
254	260	collected for testing and review. The older of these trees, maintained by
255	261	Andrew Morton, is called "-mm" (for memory management, which is how it got
256	262	started). The -mm tree integrates patches from a long list of subsystem
257		-trees; it also has some patches aimed at helping with debugging.
	263	+trees; it also has some patches aimed at helping with debugging.
258	264
259	265	Beyond that, -mm contains a significant collection of patches which have
260	266	been selected by Andrew directly. These patches may have been posted on a
...	...	@@ -264,8 +270,8 @@
264	270	patch into the mainline, it is likely to end up in -mm. Miscellaneous
265	271	patches which accumulate in -mm will eventually either be forwarded on to
266	272	an appropriate subsystem tree or be sent directly to Linus. In a typical
267		-development cycle, approximately 10% of the patches going into the mainline
268		-get there via -mm.
	273	+development cycle, approximately 5-10% of the patches going into the
	274	+mainline get there via -mm.
269	275
270	276	The current -mm patch is available in the "mmotm" (-mm of the moment)
271	277	directory at:
...	...	@@ -275,7 +281,7 @@
275	281	Use of the MMOTM tree is likely to be a frustrating experience, though;
276	282	there is a definite chance that it will not even compile.
277	283
278		-The other -next tree, started more recently, is linux-next, maintained by
	284	+The primary tree for next-cycle patch merging is linux-next, maintained by
279	285	Stephen Rothwell. The linux-next tree is, by design, a snapshot of what
280	286	the mainline is expected to look like after the next merge window closes.
281	287	Linux-next trees are announced on the linux-kernel and linux-next mailing
282	288
283	289
...	...	@@ -287,25 +293,14 @@
287	293
288	294	http://linux.f-seidel.de/linux-next/pmwiki/
289	295
290		-How the linux-next tree will fit into the development process is still
291		-changing. As of this writing, the first full development cycle involving
292		-linux-next (2.6.26) is coming to an end; thus far, it has proved to be a
293		-valuable resource for finding and fixing integration problems before the
294		-beginning of the merge window. See http://lwn.net/Articles/287155/ for
295		-more information on how linux-next has worked to set up the 2.6.27 merge
296		-window.
	296	+Linux-next has become an integral part of the kernel development process;
	297	+all patches merged during a given merge window should really have found
	298	+their way into linux-next some time before the merge window opens.
297	299
298		-Some developers have begun to suggest that linux-next should be used as the
299		-target for future development as well. The linux-next tree does tend to be
300		-far ahead of the mainline and is more representative of the tree into which
301		-any new work will be merged. The downside to this idea is that the
302		-volatility of linux-next tends to make it a difficult development target.
303		-See http://lwn.net/Articles/289013/ for more information on this topic, and
304		-stay tuned; much is still in flux where linux-next is involved.
305	300
306	301	2.4.1: STAGING TREES
307	302
308		-The kernel source tree now contains the drivers/staging/ directory, where
	303	+The kernel source tree contains the drivers/staging/ directory, where
309	304	many sub-directories for drivers or filesystems that are on their way to
310	305	being added to the kernel tree live. They remain in drivers/staging while
311	306	they still need more work; once complete, they can be moved into the
312	307
...	...	@@ -313,16 +308,24 @@
313	308	up to Linux kernel coding or quality standards, but people may want to use
314	309	them and track development.
315	310
316		-Greg Kroah-Hartman currently (as of 2.6.36) maintains the staging tree.
317		-Drivers that still need work are sent to him, with each driver having
318		-its own subdirectory in drivers/staging/. Along with the driver source
319		-files, a TODO file should be present in the directory as well. The TODO
320		-file lists the pending work that the driver needs for acceptance into
321		-the kernel proper, as well as a list of people that should be Cc'd for any
322		-patches to the driver. Staging drivers that don't currently build should
323		-have their config entries depend upon CONFIG_BROKEN. Once they can
324		-be successfully built without outside patches, CONFIG_BROKEN can be removed.
	311	+Greg Kroah-Hartman currently maintains the staging tree. Drivers that
	312	+still need work are sent to him, with each driver having its own
	313	+subdirectory in drivers/staging/. Along with the driver source files, a
	314	+TODO file should be present in the directory as well. The TODO file lists
	315	+the pending work that the driver needs for acceptance into the kernel
	316	+proper, as well as a list of people that should be Cc'd for any patches to
	317	+the driver. Current rules require that drivers contributed to staging
	318	+must, at a minimum, compile properly.
325	319
	320	+Staging can be a relatively easy way to get new drivers into the mainline
	321	+where, with luck, they will come to the attention of other developers and
	322	+improve quickly. Entry into staging is not the end of the story, though;
	323	+code in staging which is not seeing regular progress will eventually be
	324	+removed. Distributors also tend to be relatively reluctant to enable
	325	+staging drivers. So staging is, at best, a stop on the way toward becoming
	326	+a proper mainline driver.
	327	+
	328	+
326	329	2.5: TOOLS
327	330
328	331	As can be seen from the above text, the kernel development process depends
329	332
...	...	@@ -347,12 +350,8 @@
347	350
348	351	http://git-scm.com/
349	352
350		-That page has pointers to documentation and tutorials. One should be
351		-aware, in particular, of the Kernel Hacker's Guide to git, which has
352		-information specific to kernel development:
	353	+That page has pointers to documentation and tutorials.
353	354
354		- http://linux.yyz.us/git-howto.html
355		-
356	355	Among the kernel developers who do not use git, the most popular choice is
357	356	almost certainly Mercurial:
358	357
...	...	@@ -408,7 +407,7 @@
408	407	important to filter on both the topic of interest (though note that
409	408	long-running conversations can drift away from the original subject
410	409	without changing the email subject line) and the people who are
411		- participating.
	410	+ participating.
412	411
413	412	- Do not feed the trolls. If somebody is trying to stir up an angry
414	413	response, ignore them.
...	...	@@ -110,8 +110,8 @@
110	110
111	111	- The AppArmor security module made use of internal virtual filesystem
112	112	data structures in ways which were considered to be unsafe and
113		- unreliable. This code has since been significantly reworked, but
114		- remains outside of the mainline.
	113	+ unreliable. This concern (among others) kept AppArmor out of the
	114	+ mainline for years.
115	115
116	116	In each of these cases, a great deal of pain and extra work could have been
117	117	avoided with some early discussion with the kernel developers.
...	...	@@ -138,6 +138,19 @@
138	138	patches. Those are the people who will be best placed to help with a new
139	139	development project.
140	140
	141	+The task of finding the right maintainer is sometimes challenging enough
	142	+that the kernel developers have added a script to ease the process:
	143	+
	144	+ .../scripts/get_maintainer.pl
	145	+
	146	+This script will return the current maintainer(s) for a given file or
	147	+directory when given the "-f" option. If passed a patch on the
	148	+command line, it will list the maintainers who should probably receive
	149	+copies of the patch. There are a number of options regulating how hard
	150	+get_maintainer.pl will search for maintainers; please be careful about
	151	+using the more aggressive options as you may end up including developers
	152	+who have no real interest in the code you are modifying.
	153	+
141	154	If all else fails, talking to Andrew Morton can be an effective way to
142	155	track down a maintainer for a specific piece of code.
143	156
...	...	@@ -155,11 +168,15 @@
155	168	matter is (1) kernel developers tend to be busy, (2) there is no shortage
156	169	of people with grand plans and little code (or even prospect of code) to
157	170	back them up, and (3) nobody is obligated to review or comment on ideas
158		-posted by others. If a request-for-comments posting yields little in the
159		-way of comments, do not assume that it means there is no interest in the
160		-project. Unfortunately, you also cannot assume that there are no problems
161		-with your idea. The best thing to do in this situation is to proceed,
162		-keeping the community informed as you go.
	171	+posted by others. Beyond that, high-level designs often hide problems
	172	+which are only reviewed when somebody actually tries to implement those
	173	+designs; for that reason, kernel developers would rather see the code.
	174	+
	175	+If a request-for-comments posting yields little in the way of comments, do
	176	+not assume that it means there is no interest in the project.
	177	+Unfortunately, you also cannot assume that there are no problems with your
	178	+idea. The best thing to do in this situation is to proceed, keeping the
	179	+community informed as you go.
163	180
164	181
165	182	3.5: GETTING OFFICIAL BUY-IN
...	...	@@ -131,7 +131,12 @@
131	131	often does not apply to contemporary hardware. Space is time, in that a
132	132	larger program will run slower than one which is more compact.
133	133
	134	+More recent compilers take an increasingly active role in deciding whether
	135	+a given function should actually be inlined or not. So the liberal
	136	+placement of "inline" keywords may not just be excessive; it could also be
	137	+irrelevant.
134	138
	139	+
135	140	* Locking
136	141
137	142	In May, 2006, the "Devicescape" networking stack was, with great
...	...	@@ -285,6 +290,13 @@
285	290	distributor does not package it); it can then be run on the code by adding
286	291	"C=1" to your make command.
287	292
	293	+The "Coccinelle" tool (http://coccinelle.lip6.fr/) is able to find a wide
	294	+variety of potential coding problems; it can also propose fixes for those
	295	+problems. Quite a few "semantic patches" for the kernel have been packaged
	296	+under the scripts/coccinelle directory; running "make coccicheck" will run
	297	+through those semantic patches and report on any problems found. See
	298	+Documentation/coccinelle.txt for more information.
	299	+
288	300	Other kinds of portability errors are best found by compiling your code for
289	301	other architectures. If you do not happen to have an S/390 system or a
290	302	Blackfin development board handy, you can still perform the compilation
...	...	@@ -308,7 +320,9 @@
308	320	changelog. Log entries should describe the problem being solved, the form
309	321	of the solution, the people who worked on the patch, any relevant
310	322	effects on performance, and anything else that might be needed to
311		-understand the patch.
	323	+understand the patch. Be sure that the changelog says why the patch is
	324	+worth applying; a surprising number of developers fail to provide that
	325	+information.
312	326
313	327	Any code which adds a new user-space interface - including new sysfs or
314	328	/proc files - should include documentation of that interface which enables
...	...	@@ -321,7 +335,7 @@
321	335	appropriate entries to this file.
322	336
323	337	Any new configuration options must be accompanied by help text which
324		-clearly explains the options and when the user might want to select them.
	338	+clearly explains the options and when the user might want to select them.
325	339
326	340	Internal API information for many subsystems is documented by way of
327	341	specially-formatted comments; these comments can be extracted and formatted
...	...	@@ -372,7 +386,8 @@
372	386	lead to literally hundreds or thousands of changes - many of which are
373	387	likely to conflict with work being done by other developers. Needless to
374	388	say, this can be a large job, so it is best to be sure that the
375		-justification is solid.
	389	+justification is solid. Note that the Coccinelle tool can help with
	390	+wide-ranging API changes.
376	391
377	392	When making an incompatible API change, one should, whenever possible,
378	393	ensure that code which has not been updated is caught by the compiler.
...	...	@@ -60,13 +60,16 @@
60	60
61	61	Patches must be prepared against a specific version of the kernel. As a
62	62	general rule, a patch should be based on the current mainline as found in
63		-Linus's git tree. It may become necessary to make versions against -mm,
64		-linux-next, or a subsystem tree, though, to facilitate wider testing and
65		-review. Depending on the area of your patch and what is going on
66		-elsewhere, basing a patch against these other trees can require a
67		-significant amount of work resolving conflicts and dealing with API
68		-changes.
	63	+Linus's git tree. When basing on mainline, start with a well-known release
	64	+point - a stable or -rc release - rather than branching off the mainline at
	65	+an arbitrary spot.
69	66
	67	+It may become necessary to make versions against -mm, linux-next, or a
	68	+subsystem tree, though, to facilitate wider testing and review. Depending
	69	+on the area of your patch and what is going on elsewhere, basing a patch
	70	+against these other trees can require a significant amount of work
	71	+resolving conflicts and dealing with API changes.
	72	+
70	73	Only the most simple changes should be formatted as a single patch;
71	74	everything else should be made as a logical series of changes. Splitting
72	75	up patches is a bit of an art; some developers spend a long time figuring
73	76
...	...	@@ -100,11 +103,11 @@
100	103	result is a broken kernel, you will make life harder for developers and
101	104	users who are engaging in the noble work of tracking down problems.
102	105
103		- - Do not overdo it, though. One developer recently posted a set of edits
	106	+ - Do not overdo it, though. One developer once posted a set of edits
104	107	to a single file as 500 separate patches - an act which did not make him
105	108	the most popular person on the kernel mailing list. A single patch can
106	109	be reasonably large as long as it still contains a single logical
107		- change.
	110	+ change.
108	111
109	112	- It can be tempting to add a whole new infrastructure with a series of
110	113	patches, but to leave that infrastructure unused until the final patch
...	...	@@ -162,7 +165,8 @@
162	165	for the change as well as possible given the one-line constraint. The
163	166	detailed description can then amplify on those topics and provide any
164	167	needed additional information. If the patch fixes a bug, cite the commit
165		-which introduced the bug if possible. If a problem is associated with
	168	+which introduced the bug if possible (and please provide both the commit ID
	169	+and the title when citing commits). If a problem is associated with
166	170	specific log or compiler output, include that output to help others
167	171	searching for a solution to the same problem. If the change is meant to
168	172	support other changes coming in later patch, say so. If internal APIs are
...	...	@@ -230,7 +234,7 @@
230	234	which have had gratuitous white-space changes or line wrapping performed
231	235	by the mail client will not apply at the other end, and often will not
232	236	be examined in any detail. If there is any doubt at all, mail the patch
233		- to yourself and convince yourself that it shows up intact.
	237	+ to yourself and convince yourself that it shows up intact.
234	238
235	239	Documentation/email-clients.txt has some helpful hints on making
236	240	specific mail clients work for sending patches.
...	...	@@ -287,7 +291,7 @@
287	291
288	292	where "nn" is the ordinal number of the patch, "mm" is the total number of
289	293	patches in the series, and "subsys" is the name of the affected subsystem.
290		-Clearly, nn/mm can be omitted for a single, standalone patch.
	294	+Clearly, nn/mm can be omitted for a single, standalone patch.
291	295
292	296	If you have a significant series of patches, it is customary to send an
293	297	introductory description as part zero. This convention is not universally
...	...	@@ -299,6 +303,6 @@
299	303	sent as a reply to the first part so that they all thread together at the
300	304	receiving end. Tools like git and quilt have commands to mail out a set of
301	305	patches with the proper threading. If you have a long series, though, and
302		-are using git, please provide the --no-chain-reply-to option to avoid
	306	+are using git, please stay away from the --chain-reply-to option to avoid
303	307	creating exceptionally deep nesting.
...	...	@@ -66,6 +66,11 @@
66	66	that you don't realize that something is fundamentally wrong or, perhaps,
67	67	you're not even solving the right problem.
68	68
	69	+Andrew Morton has suggested that every review comment which does not result
	70	+in a code change should result in an additional code comment instead; that
	71	+can help future reviewers avoid the questions which came up the first time
	72	+around.
	73	+
69	74	One fatal mistake is to ignore review comments in the hope that they will
70	75	go away. They will not go away. If you repost code without having
71	76	responded to the comments you got the time before, you're likely to find
...	...	@@ -100,7 +105,7 @@
100	105	subsystem to the next; each maintainer has his or her own way of doing
101	106	things. In particular, there may be more than one tree - one, perhaps,
102	107	dedicated to patches planned for the next merge window, and another for
103		-longer-term work.
	108	+longer-term work.
104	109
105	110	For patches applying to areas for which there is no obvious subsystem tree
106	111	(memory management patches, for example), the default tree often ends up
...	...	@@ -109,11 +114,10 @@
109	114
110	115	Inclusion into a subsystem tree can bring a higher level of visibility to a
111	116	patch. Now other developers working with that tree will get the patch by
112		-default. Subsystem trees typically feed into -mm and linux-next as well,
113		-making their contents visible to the development community as a whole. At
114		-this point, there's a good chance that you will get more comments from a
115		-new set of reviewers; these comments need to be answered as in the previous
116		-round.
	117	+default. Subsystem trees typically feed linux-next as well, making their
	118	+contents visible to the development community as a whole. At this point,
	119	+there's a good chance that you will get more comments from a new set of
	120	+reviewers; these comments need to be answered as in the previous round.
117	121
118	122	What may also happen at this point, depending on the nature of your patch,
119	123	is that conflicts with work being done by others turn up. In the worst
...	...	@@ -119,7 +119,7 @@
119	119	to trust things without then having to go and check every
120	120	individual change by hand.
121	121
122		-(http://lwn.net/Articles/224135/).
	122	+(http://lwn.net/Articles/224135/).
123	123
124	124	To avoid this kind of situation, ensure that all patches within a given
125	125	branch stick closely to the associated topic; a "driver fixes" branch
...	...	@@ -138,7 +138,7 @@
138	138	your tree is, what branch to pull, and what changes will result from the
139	139	pull. The git request-pull command can be helpful in this regard; it will
140	140	format the request as other developers expect, and will also check to be
141		-sure that you have remembered to push those changes to the public server.
	141	+sure that you have remembered to push those changes to the public server.
142	142
143	143
144	144	7.2: REVIEWING PATCHES