diff options
| -rw-r--r-- | Documentation/development-process/1.Intro | 18 | ||||
| -rw-r--r-- | Documentation/development-process/2.Process | 177 | ||||
| -rw-r--r-- | Documentation/development-process/3.Early-stage | 31 | ||||
| -rw-r--r-- | Documentation/development-process/4.Coding | 21 | ||||
| -rw-r--r-- | Documentation/development-process/5.Posting | 28 | ||||
| -rw-r--r-- | Documentation/development-process/6.Followthrough | 16 | ||||
| -rw-r--r-- | Documentation/development-process/7.AdvancedTopics | 4 |
7 files changed, 167 insertions, 128 deletions
diff --git a/Documentation/development-process/1.Intro b/Documentation/development-process/1.Intro index 8cc2cba2b10..9b614480aa8 100644 --- a/Documentation/development-process/1.Intro +++ b/Documentation/development-process/1.Intro | |||
| @@ -56,13 +56,13 @@ information on kernel development. | |||
| 56 | 56 | ||
| 57 | 1.2: WHAT THIS DOCUMENT IS ABOUT | 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 | 59 | The Linux kernel, at over 8 million lines of code and well over 1000 |
| 60 | contributors, is one of the largest and most active free software projects | 60 | contributors to each release, is one of the largest and most active free |
| 61 | in existence. Since its humble beginning in 1991, this kernel has evolved | 61 | software projects in existence. Since its humble beginning in 1991, this |
| 62 | into a best-of-breed operating system component which runs on pocket-sized | 62 | kernel has evolved into a best-of-breed operating system component which |
| 63 | digital music players, desktop PCs, the largest supercomputers in | 63 | runs on pocket-sized digital music players, desktop PCs, the largest |
| 64 | existence, and all types of systems in between. It is a robust, efficient, | 64 | supercomputers in existence, and all types of systems in between. It is a |
| 65 | and scalable solution for almost any situation. | 65 | robust, efficient, and scalable solution for almost any situation. |
| 66 | 66 | ||
| 67 | With the growth of Linux has come an increase in the number of developers | 67 | With the growth of Linux has come an increase in the number of developers |
| 68 | (and companies) wishing to participate in its development. Hardware | 68 | (and companies) wishing to participate in its development. Hardware |
| @@ -115,7 +115,7 @@ This document was written by Jonathan Corbet, corbet@lwn.net. It has been | |||
| 115 | improved by comments from Johannes Berg, James Berry, Alex Chiang, Roland | 115 | improved by comments from Johannes Berg, James Berry, Alex Chiang, Roland |
| 116 | Dreier, Randy Dunlap, Jake Edge, Jiri Kosina, Matt Mackall, Arthur Marsh, | 116 | Dreier, Randy Dunlap, Jake Edge, Jiri Kosina, Matt Mackall, Arthur Marsh, |
| 117 | Amanda McPherson, Andrew Morton, Andrew Price, Tsugikazu Shibata, and | 117 | Amanda McPherson, Andrew Morton, Andrew Price, Tsugikazu Shibata, and |
| 118 | Jochen Voß. | 118 | Jochen Voß. |
| 119 | 119 | ||
| 120 | This work was supported by the Linux Foundation; thanks especially to | 120 | This work was supported by the Linux Foundation; thanks especially to |
| 121 | Amanda McPherson, who saw the value of this effort and made it all happen. | 121 | Amanda McPherson, who saw the value of this effort and made it all happen. |
| @@ -221,7 +221,7 @@ include: | |||
| 221 | - Everything that was said above about code review applies doubly to | 221 | - Everything that was said above about code review applies doubly to |
| 222 | closed-source code. Since this code is not available at all, it cannot | 222 | closed-source code. Since this code is not available at all, it cannot |
| 223 | have been reviewed by the community and will, beyond doubt, have serious | 223 | have been reviewed by the community and will, beyond doubt, have serious |
| 224 | problems. | 224 | problems. |
| 225 | 225 | ||
| 226 | Makers of embedded systems, in particular, may be tempted to disregard much | 226 | Makers of embedded systems, in particular, may be tempted to disregard much |
| 227 | of what has been said in this section in the belief that they are shipping | 227 | of what has been said in this section in the belief that they are shipping |
diff --git a/Documentation/development-process/2.Process b/Documentation/development-process/2.Process index 911a4518634..4823577c650 100644 --- a/Documentation/development-process/2.Process +++ b/Documentation/development-process/2.Process | |||
| @@ -14,16 +14,15 @@ The kernel developers use a loosely time-based release process, with a new | |||
| 14 | major kernel release happening every two or three months. The recent | 14 | major kernel release happening every two or three months. The recent |
| 15 | release history looks like this: | 15 | release history looks like this: |
| 16 | 16 | ||
| 17 | 2.6.26 July 13, 2008 | 17 | 2.6.38 March 14, 2011 |
| 18 | 2.6.25 April 16, 2008 | 18 | 2.6.37 January 4, 2011 |
| 19 | 2.6.24 January 24, 2008 | 19 | 2.6.36 October 20, 2010 |
| 20 | 2.6.23 October 9, 2007 | 20 | 2.6.35 August 1, 2010 |
| 21 | 2.6.22 July 8, 2007 | 21 | 2.6.34 May 15, 2010 |
| 22 | 2.6.21 April 25, 2007 | 22 | 2.6.33 February 24, 2010 |
| 23 | 2.6.20 February 4, 2007 | ||
| 24 | 23 | ||
| 25 | Every 2.6.x release is a major kernel release with new features, internal | 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 | changesets with changes to several hundred thousand lines of code. 2.6 is | 26 | changesets with changes to several hundred thousand lines of code. 2.6 is |
| 28 | thus the leading edge of Linux kernel development; the kernel uses a | 27 | thus the leading edge of Linux kernel development; the kernel uses a |
| 29 | rolling development model which is continually integrating major changes. | 28 | rolling development model which is continually integrating major changes. |
| @@ -42,13 +41,13 @@ merge window do not come out of thin air; they have been collected, tested, | |||
| 42 | and staged ahead of time. How that process works will be described in | 41 | and staged ahead of time. How that process works will be described in |
| 43 | detail later on). | 42 | detail later on). |
| 44 | 43 | ||
| 45 | The merge window lasts for two weeks. At the end of this time, Linus | 44 | The merge window lasts for approximately two weeks. At the end of this |
| 46 | Torvalds will declare that the window is closed and release the first of | 45 | time, Linus Torvalds will declare that the window is closed and release the |
| 47 | the "rc" kernels. For the kernel which is destined to be 2.6.26, for | 46 | first of the "rc" kernels. For the kernel which is destined to be 2.6.40, |
| 48 | example, the release which happens at the end of the merge window will be | 47 | for example, the release which happens at the end of the merge window will |
| 49 | called 2.6.26-rc1. The -rc1 release is the signal that the time to merge | 48 | be called 2.6.40-rc1. The -rc1 release is the signal that the time to |
| 50 | new features has passed, and that the time to stabilize the next kernel has | 49 | merge new features has passed, and that the time to stabilize the next |
| 51 | begun. | 50 | kernel has begun. |
| 52 | 51 | ||
| 53 | Over the next six to ten weeks, only patches which fix problems should be | 52 | Over the next six to ten weeks, only patches which fix problems should be |
| 54 | submitted to the mainline. On occasion a more significant change will be | 53 | submitted to the mainline. On occasion a more significant change will be |
| @@ -66,20 +65,19 @@ will get up to somewhere between -rc6 and -rc9 before the kernel is | |||
| 66 | considered to be sufficiently stable and the final 2.6.x release is made. | 65 | considered to be sufficiently stable and the final 2.6.x release is made. |
| 67 | At that point the whole process starts over again. | 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 | 68 | As an example, here is how the 2.6.38 development cycle went (all dates in |
| 70 | 2008): | 69 | 2011): |
| 71 | 70 | ||
| 72 | January 24 2.6.24 stable release | 71 | January 4 2.6.37 stable release |
| 73 | February 10 2.6.25-rc1, merge window closes | 72 | January 18 2.6.38-rc1, merge window closes |
| 74 | February 15 2.6.25-rc2 | 73 | January 21 2.6.38-rc2 |
| 75 | February 24 2.6.25-rc3 | 74 | February 1 2.6.38-rc3 |
| 76 | March 4 2.6.25-rc4 | 75 | February 7 2.6.38-rc4 |
| 77 | March 9 2.6.25-rc5 | 76 | February 15 2.6.38-rc5 |
| 78 | March 16 2.6.25-rc6 | 77 | February 21 2.6.38-rc6 |
| 79 | March 25 2.6.25-rc7 | 78 | March 1 2.6.38-rc7 |
| 80 | April 1 2.6.25-rc8 | 79 | March 7 2.6.38-rc8 |
| 81 | April 11 2.6.25-rc9 | 80 | March 14 2.6.38 stable release |
| 82 | April 16 2.6.25 stable release | ||
| 83 | 81 | ||
| 84 | How do the developers decide when to close the development cycle and create | 82 | How do the developers decide when to close the development cycle and create |
| 85 | the stable release? The most significant metric used is the list of | 83 | the stable release? The most significant metric used is the list of |
| @@ -87,7 +85,7 @@ regressions from previous releases. No bugs are welcome, but those which | |||
| 87 | break systems which worked in the past are considered to be especially | 85 | break systems which worked in the past are considered to be especially |
| 88 | serious. For this reason, patches which cause regressions are looked upon | 86 | serious. For this reason, patches which cause regressions are looked upon |
| 89 | unfavorably and are quite likely to be reverted during the stabilization | 87 | unfavorably and are quite likely to be reverted during the stabilization |
| 90 | period. | 88 | period. |
| 91 | 89 | ||
| 92 | The developers' goal is to fix all known regressions before the stable | 90 | The developers' goal is to fix all known regressions before the stable |
| 93 | release is made. In the real world, this kind of perfection is hard to | 91 | release is made. In the real world, this kind of perfection is hard to |
| @@ -99,26 +97,34 @@ kernels go out with a handful of known regressions though, hopefully, none | |||
| 99 | of them are serious. | 97 | of them are serious. |
| 100 | 98 | ||
| 101 | Once a stable release is made, its ongoing maintenance is passed off to the | 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. | 100 | "stable team," currently consisting of Greg Kroah-Hartman. The stable team |
| 103 | The stable team will release occasional updates to the stable release using | 101 | will release occasional updates to the stable release using the 2.6.x.y |
| 104 | the 2.6.x.y numbering scheme. To be considered for an update release, a | 102 | numbering scheme. To be considered for an update release, a patch must (1) |
| 105 | patch must (1) fix a significant bug, and (2) already be merged into the | 103 | fix a significant bug, and (2) already be merged into the mainline for the |
| 106 | mainline for the next development kernel. Continuing our 2.6.25 example, | 104 | next development kernel. Kernels will typically receive stable updates for |
| 107 | the history (as of this writing) is: | 105 | a little more than one development cycle past their initial release. So, |
| 108 | 106 | for example, the 2.6.36 kernel's history looked like: | |
| 109 | May 1 2.6.25.1 | 107 | |
| 110 | May 6 2.6.25.2 | 108 | October 10 2.6.36 stable release |
| 111 | May 9 2.6.25.3 | 109 | November 22 2.6.36.1 |
| 112 | May 15 2.6.25.4 | 110 | December 9 2.6.36.2 |
| 113 | June 7 2.6.25.5 | 111 | January 7 2.6.36.3 |
| 114 | June 9 2.6.25.6 | 112 | February 17 2.6.36.4 |
| 115 | June 16 2.6.25.7 | 113 | |
| 116 | June 21 2.6.25.8 | 114 | 2.6.36.4 was the final stable update for the 2.6.36 release. |
| 117 | June 24 2.6.25.9 | 115 | |
| 118 | 116 | Some kernels are designated "long term" kernels; they will receive support | |
| 119 | Stable updates for a given kernel are made for approximately six months; | 117 | for a longer period. As of this writing, the current long term kernels |
| 120 | after that, the maintenance of stable releases is solely the responsibility | 118 | and their maintainers are: |
| 121 | of the distributors which have shipped that particular kernel. | 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. | ||
| 122 | 128 | ||
| 123 | 129 | ||
| 124 | 2.2: THE LIFECYCLE OF A PATCH | 130 | 2.2: THE LIFECYCLE OF A PATCH |
| @@ -130,7 +136,7 @@ each patch implements a change which is desirable to have in the mainline. | |||
| 130 | This process can happen quickly for minor fixes, or, in the case of large | 136 | This process can happen quickly for minor fixes, or, in the case of large |
| 131 | and controversial changes, go on for years. Much developer frustration | 137 | and controversial changes, go on for years. Much developer frustration |
| 132 | comes from a lack of understanding of this process or from attempts to | 138 | comes from a lack of understanding of this process or from attempts to |
| 133 | circumvent it. | 139 | circumvent it. |
| 134 | 140 | ||
| 135 | In the hopes of reducing that frustration, this document will describe how | 141 | In the hopes of reducing that frustration, this document will describe how |
| 136 | a patch gets into the kernel. What follows below is an introduction which | 142 | a patch gets into the kernel. What follows below is an introduction which |
| @@ -193,8 +199,8 @@ involved. | |||
| 193 | 2.3: HOW PATCHES GET INTO THE KERNEL | 199 | 2.3: HOW PATCHES GET INTO THE KERNEL |
| 194 | 200 | ||
| 195 | There is exactly one person who can merge patches into the mainline kernel | 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 | 202 | repository: Linus Torvalds. But, of the over 9,500 patches which went |
| 197 | into the 2.6.25 kernel, only 250 (around 2%) were directly chosen by Linus | 203 | into the 2.6.38 kernel, only 112 (around 1.3%) were directly chosen by Linus |
| 198 | himself. The kernel project has long since grown to a size where no single | 204 | himself. The kernel project has long since grown to a size where no single |
| 199 | developer could possibly inspect and select every patch unassisted. The | 205 | developer could possibly inspect and select every patch unassisted. The |
| 200 | way the kernel developers have addressed this growth is through the use of | 206 | way the kernel developers have addressed this growth is through the use of |
| @@ -229,7 +235,7 @@ first in trees dedicated to network device drivers, wireless networking, | |||
| 229 | etc. This chain of repositories can be arbitrarily long, though it rarely | 235 | etc. This chain of repositories can be arbitrarily long, though it rarely |
| 230 | exceeds two or three links. Since each maintainer in the chain trusts | 236 | exceeds two or three links. Since each maintainer in the chain trusts |
| 231 | those managing lower-level trees, this process is known as the "chain of | 237 | those managing lower-level trees, this process is known as the "chain of |
| 232 | trust." | 238 | trust." |
| 233 | 239 | ||
| 234 | Clearly, in a system like this, getting patches into the kernel depends on | 240 | Clearly, in a system like this, getting patches into the kernel depends on |
| 235 | finding the right maintainer. Sending patches directly to Linus is not | 241 | finding the right maintainer. Sending patches directly to Linus is not |
| @@ -254,7 +260,7 @@ The answer comes in the form of -next trees, where subsystem trees are | |||
| 254 | collected for testing and review. The older of these trees, maintained by | 260 | collected for testing and review. The older of these trees, maintained by |
| 255 | Andrew Morton, is called "-mm" (for memory management, which is how it got | 261 | Andrew Morton, is called "-mm" (for memory management, which is how it got |
| 256 | started). The -mm tree integrates patches from a long list of subsystem | 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 | Beyond that, -mm contains a significant collection of patches which have | 265 | Beyond that, -mm contains a significant collection of patches which have |
| 260 | been selected by Andrew directly. These patches may have been posted on a | 266 | been selected by Andrew directly. These patches may have been posted on a |
| @@ -264,8 +270,8 @@ subsystem tree of last resort; if there is no other obvious path for a | |||
| 264 | patch into the mainline, it is likely to end up in -mm. Miscellaneous | 270 | patch into the mainline, it is likely to end up in -mm. Miscellaneous |
| 265 | patches which accumulate in -mm will eventually either be forwarded on to | 271 | patches which accumulate in -mm will eventually either be forwarded on to |
| 266 | an appropriate subsystem tree or be sent directly to Linus. In a typical | 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 | 273 | development cycle, approximately 5-10% of the patches going into the |
| 268 | get there via -mm. | 274 | mainline get there via -mm. |
| 269 | 275 | ||
| 270 | The current -mm patch is available in the "mmotm" (-mm of the moment) | 276 | The current -mm patch is available in the "mmotm" (-mm of the moment) |
| 271 | directory at: | 277 | directory at: |
| @@ -275,7 +281,7 @@ directory at: | |||
| 275 | Use of the MMOTM tree is likely to be a frustrating experience, though; | 281 | Use of the MMOTM tree is likely to be a frustrating experience, though; |
| 276 | there is a definite chance that it will not even compile. | 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 | Stephen Rothwell. The linux-next tree is, by design, a snapshot of what | 285 | Stephen Rothwell. The linux-next tree is, by design, a snapshot of what |
| 280 | the mainline is expected to look like after the next merge window closes. | 286 | the mainline is expected to look like after the next merge window closes. |
| 281 | Linux-next trees are announced on the linux-kernel and linux-next mailing | 287 | Linux-next trees are announced on the linux-kernel and linux-next mailing |
| @@ -287,25 +293,14 @@ Some information about linux-next has been gathered at: | |||
| 287 | 293 | ||
| 288 | http://linux.f-seidel.de/linux-next/pmwiki/ | 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 | 296 | Linux-next has become an integral part of the kernel development process; |
| 291 | changing. As of this writing, the first full development cycle involving | 297 | all patches merged during a given merge window should really have found |
| 292 | linux-next (2.6.26) is coming to an end; thus far, it has proved to be a | 298 | their way into linux-next some time before the merge window opens. |
| 293 | valuable resource for finding and fixing integration problems before the | 299 | |
| 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. | ||
| 297 | |||
| 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 | 2.4.1: STAGING TREES | 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 | many sub-directories for drivers or filesystems that are on their way to | 304 | many sub-directories for drivers or filesystems that are on their way to |
| 310 | being added to the kernel tree live. They remain in drivers/staging while | 305 | being added to the kernel tree live. They remain in drivers/staging while |
| 311 | they still need more work; once complete, they can be moved into the | 306 | they still need more work; once complete, they can be moved into the |
| @@ -313,15 +308,23 @@ kernel proper. This is a way to keep track of drivers that aren't | |||
| 313 | up to Linux kernel coding or quality standards, but people may want to use | 308 | up to Linux kernel coding or quality standards, but people may want to use |
| 314 | them and track development. | 309 | them and track development. |
| 315 | 310 | ||
| 316 | Greg Kroah-Hartman currently (as of 2.6.36) maintains the staging tree. | 311 | Greg Kroah-Hartman currently maintains the staging tree. Drivers that |
| 317 | Drivers that still need work are sent to him, with each driver having | 312 | still need work are sent to him, with each driver having its own |
| 318 | its own subdirectory in drivers/staging/. Along with the driver source | 313 | subdirectory in drivers/staging/. Along with the driver source files, a |
| 319 | files, a TODO file should be present in the directory as well. The TODO | 314 | TODO file should be present in the directory as well. The TODO file lists |
| 320 | file lists the pending work that the driver needs for acceptance into | 315 | the pending work that the driver needs for acceptance into the kernel |
| 321 | the kernel proper, as well as a list of people that should be Cc'd for any | 316 | proper, as well as a list of people that should be Cc'd for any patches to |
| 322 | patches to the driver. Staging drivers that don't currently build should | 317 | the driver. Current rules require that drivers contributed to staging |
| 323 | have their config entries depend upon CONFIG_BROKEN. Once they can | 318 | must, at a minimum, compile properly. |
| 324 | be successfully built without outside patches, CONFIG_BROKEN can be removed. | 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 | |||
| 325 | 328 | ||
| 326 | 2.5: TOOLS | 329 | 2.5: TOOLS |
| 327 | 330 | ||
| @@ -347,11 +350,7 @@ page at: | |||
| 347 | 350 | ||
| 348 | http://git-scm.com/ | 351 | http://git-scm.com/ |
| 349 | 352 | ||
| 350 | That page has pointers to documentation and tutorials. One should be | 353 | That page has pointers to documentation and tutorials. |
| 351 | aware, in particular, of the Kernel Hacker's Guide to git, which has | ||
| 352 | information specific to kernel development: | ||
| 353 | |||
| 354 | http://linux.yyz.us/git-howto.html | ||
| 355 | 354 | ||
| 356 | Among the kernel developers who do not use git, the most popular choice is | 355 | Among the kernel developers who do not use git, the most popular choice is |
| 357 | almost certainly Mercurial: | 356 | almost certainly Mercurial: |
| @@ -408,7 +407,7 @@ There are a few hints which can help with linux-kernel survival: | |||
| 408 | important to filter on both the topic of interest (though note that | 407 | important to filter on both the topic of interest (though note that |
| 409 | long-running conversations can drift away from the original subject | 408 | long-running conversations can drift away from the original subject |
| 410 | without changing the email subject line) and the people who are | 409 | without changing the email subject line) and the people who are |
| 411 | participating. | 410 | participating. |
| 412 | 411 | ||
| 413 | - Do not feed the trolls. If somebody is trying to stir up an angry | 412 | - Do not feed the trolls. If somebody is trying to stir up an angry |
| 414 | response, ignore them. | 413 | response, ignore them. |
diff --git a/Documentation/development-process/3.Early-stage b/Documentation/development-process/3.Early-stage index 307a159a70c..f87ba7b3fba 100644 --- a/Documentation/development-process/3.Early-stage +++ b/Documentation/development-process/3.Early-stage | |||
| @@ -110,8 +110,8 @@ the kernel community's standards. Some examples include: | |||
| 110 | 110 | ||
| 111 | - The AppArmor security module made use of internal virtual filesystem | 111 | - The AppArmor security module made use of internal virtual filesystem |
| 112 | data structures in ways which were considered to be unsafe and | 112 | data structures in ways which were considered to be unsafe and |
| 113 | unreliable. This code has since been significantly reworked, but | 113 | unreliable. This concern (among others) kept AppArmor out of the |
| 114 | remains outside of the mainline. | 114 | mainline for years. |
| 115 | 115 | ||
| 116 | In each of these cases, a great deal of pain and extra work could have been | 116 | In each of these cases, a great deal of pain and extra work could have been |
| 117 | avoided with some early discussion with the kernel developers. | 117 | avoided with some early discussion with the kernel developers. |
| @@ -138,6 +138,19 @@ patches, and who, if anybody, is attaching Signed-off-by lines to those | |||
| 138 | patches. Those are the people who will be best placed to help with a new | 138 | patches. Those are the people who will be best placed to help with a new |
| 139 | development project. | 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 | If all else fails, talking to Andrew Morton can be an effective way to | 154 | If all else fails, talking to Andrew Morton can be an effective way to |
| 142 | track down a maintainer for a specific piece of code. | 155 | track down a maintainer for a specific piece of code. |
| 143 | 156 | ||
| @@ -155,11 +168,15 @@ reaction, but, instead, little or no reaction at all. The sad truth of the | |||
| 155 | matter is (1) kernel developers tend to be busy, (2) there is no shortage | 168 | matter is (1) kernel developers tend to be busy, (2) there is no shortage |
| 156 | of people with grand plans and little code (or even prospect of code) to | 169 | of people with grand plans and little code (or even prospect of code) to |
| 157 | back them up, and (3) nobody is obligated to review or comment on ideas | 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 | 171 | posted by others. Beyond that, high-level designs often hide problems |
| 159 | way of comments, do not assume that it means there is no interest in the | 172 | which are only reviewed when somebody actually tries to implement those |
| 160 | project. Unfortunately, you also cannot assume that there are no problems | 173 | designs; for that reason, kernel developers would rather see the code. |
| 161 | with your idea. The best thing to do in this situation is to proceed, | 174 | |
| 162 | keeping the community informed as you go. | 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 | 3.5: GETTING OFFICIAL BUY-IN | 182 | 3.5: GETTING OFFICIAL BUY-IN |
diff --git a/Documentation/development-process/4.Coding b/Documentation/development-process/4.Coding index 2278693c8ff..f3f1a469443 100644 --- a/Documentation/development-process/4.Coding +++ b/Documentation/development-process/4.Coding | |||
| @@ -131,6 +131,11 @@ classic time/space tradeoff taught in beginning data structures classes | |||
| 131 | often does not apply to contemporary hardware. Space *is* time, in that a | 131 | often does not apply to contemporary hardware. Space *is* time, in that a |
| 132 | larger program will run slower than one which is more compact. | 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. | ||
| 138 | |||
| 134 | 139 | ||
| 135 | * Locking | 140 | * Locking |
| 136 | 141 | ||
| @@ -285,6 +290,13 @@ be found at https://sparse.wiki.kernel.org/index.php/Main_Page if your | |||
| 285 | distributor does not package it); it can then be run on the code by adding | 290 | distributor does not package it); it can then be run on the code by adding |
| 286 | "C=1" to your make command. | 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 | Other kinds of portability errors are best found by compiling your code for | 300 | Other kinds of portability errors are best found by compiling your code for |
| 289 | other architectures. If you do not happen to have an S/390 system or a | 301 | other architectures. If you do not happen to have an S/390 system or a |
| 290 | Blackfin development board handy, you can still perform the compilation | 302 | Blackfin development board handy, you can still perform the compilation |
| @@ -308,7 +320,9 @@ The first piece of documentation for any patch is its associated | |||
| 308 | changelog. Log entries should describe the problem being solved, the form | 320 | changelog. Log entries should describe the problem being solved, the form |
| 309 | of the solution, the people who worked on the patch, any relevant | 321 | of the solution, the people who worked on the patch, any relevant |
| 310 | effects on performance, and anything else that might be needed to | 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 | Any code which adds a new user-space interface - including new sysfs or | 327 | Any code which adds a new user-space interface - including new sysfs or |
| 314 | /proc files - should include documentation of that interface which enables | 328 | /proc files - should include documentation of that interface which enables |
| @@ -321,7 +335,7 @@ boot-time parameters. Any patch which adds new parameters should add the | |||
| 321 | appropriate entries to this file. | 335 | appropriate entries to this file. |
| 322 | 336 | ||
| 323 | Any new configuration options must be accompanied by help text which | 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 | Internal API information for many subsystems is documented by way of | 340 | Internal API information for many subsystems is documented by way of |
| 327 | specially-formatted comments; these comments can be extracted and formatted | 341 | specially-formatted comments; these comments can be extracted and formatted |
| @@ -372,7 +386,8 @@ which is broken by the change. For a widely-used function, this duty can | |||
| 372 | lead to literally hundreds or thousands of changes - many of which are | 386 | lead to literally hundreds or thousands of changes - many of which are |
| 373 | likely to conflict with work being done by other developers. Needless to | 387 | likely to conflict with work being done by other developers. Needless to |
| 374 | say, this can be a large job, so it is best to be sure that the | 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 | When making an incompatible API change, one should, whenever possible, | 392 | When making an incompatible API change, one should, whenever possible, |
| 378 | ensure that code which has not been updated is caught by the compiler. | 393 | ensure that code which has not been updated is caught by the compiler. |
diff --git a/Documentation/development-process/5.Posting b/Documentation/development-process/5.Posting index f622c1e9f0f..903a2546f13 100644 --- a/Documentation/development-process/5.Posting +++ b/Documentation/development-process/5.Posting | |||
| @@ -60,12 +60,15 @@ even in the short term. | |||
| 60 | 60 | ||
| 61 | Patches must be prepared against a specific version of the kernel. As a | 61 | Patches must be prepared against a specific version of the kernel. As a |
| 62 | general rule, a patch should be based on the current mainline as found in | 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, | 63 | Linus's git tree. When basing on mainline, start with a well-known release |
| 64 | linux-next, or a subsystem tree, though, to facilitate wider testing and | 64 | point - a stable or -rc release - rather than branching off the mainline at |
| 65 | review. Depending on the area of your patch and what is going on | 65 | an arbitrary spot. |
| 66 | elsewhere, basing a patch against these other trees can require a | 66 | |
| 67 | significant amount of work resolving conflicts and dealing with API | 67 | It may become necessary to make versions against -mm, linux-next, or a |
| 68 | changes. | 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. | ||
| 69 | 72 | ||
| 70 | Only the most simple changes should be formatted as a single patch; | 73 | Only the most simple changes should be formatted as a single patch; |
| 71 | everything else should be made as a logical series of changes. Splitting | 74 | everything else should be made as a logical series of changes. Splitting |
| @@ -100,11 +103,11 @@ rules of thumb, however, which can help considerably: | |||
| 100 | result is a broken kernel, you will make life harder for developers and | 103 | result is a broken kernel, you will make life harder for developers and |
| 101 | users who are engaging in the noble work of tracking down problems. | 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 | to a single file as 500 separate patches - an act which did not make him | 107 | to a single file as 500 separate patches - an act which did not make him |
| 105 | the most popular person on the kernel mailing list. A single patch can | 108 | the most popular person on the kernel mailing list. A single patch can |
| 106 | be reasonably large as long as it still contains a single *logical* | 109 | be reasonably large as long as it still contains a single *logical* |
| 107 | change. | 110 | change. |
| 108 | 111 | ||
| 109 | - It can be tempting to add a whole new infrastructure with a series of | 112 | - It can be tempting to add a whole new infrastructure with a series of |
| 110 | patches, but to leave that infrastructure unused until the final patch | 113 | patches, but to leave that infrastructure unused until the final patch |
| @@ -162,7 +165,8 @@ To that end, the summary line should describe the effects of and motivation | |||
| 162 | for the change as well as possible given the one-line constraint. The | 165 | for the change as well as possible given the one-line constraint. The |
| 163 | detailed description can then amplify on those topics and provide any | 166 | detailed description can then amplify on those topics and provide any |
| 164 | needed additional information. If the patch fixes a bug, cite the commit | 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 | specific log or compiler output, include that output to help others | 170 | specific log or compiler output, include that output to help others |
| 167 | searching for a solution to the same problem. If the change is meant to | 171 | searching for a solution to the same problem. If the change is meant to |
| 168 | support other changes coming in later patch, say so. If internal APIs are | 172 | support other changes coming in later patch, say so. If internal APIs are |
| @@ -230,7 +234,7 @@ take care of: | |||
| 230 | which have had gratuitous white-space changes or line wrapping performed | 234 | which have had gratuitous white-space changes or line wrapping performed |
| 231 | by the mail client will not apply at the other end, and often will not | 235 | by the mail client will not apply at the other end, and often will not |
| 232 | be examined in any detail. If there is any doubt at all, mail the patch | 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 | Documentation/email-clients.txt has some helpful hints on making | 239 | Documentation/email-clients.txt has some helpful hints on making |
| 236 | specific mail clients work for sending patches. | 240 | specific mail clients work for sending patches. |
| @@ -287,7 +291,7 @@ something like: | |||
| 287 | 291 | ||
| 288 | where "nn" is the ordinal number of the patch, "mm" is the total number of | 292 | where "nn" is the ordinal number of the patch, "mm" is the total number of |
| 289 | patches in the series, and "subsys" is the name of the affected subsystem. | 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 | If you have a significant series of patches, it is customary to send an | 296 | If you have a significant series of patches, it is customary to send an |
| 293 | introductory description as part zero. This convention is not universally | 297 | introductory description as part zero. This convention is not universally |
| @@ -299,5 +303,5 @@ In general, the second and following parts of a multi-part patch should be | |||
| 299 | sent as a reply to the first part so that they all thread together at the | 303 | sent as a reply to the first part so that they all thread together at the |
| 300 | receiving end. Tools like git and quilt have commands to mail out a set of | 304 | receiving end. Tools like git and quilt have commands to mail out a set of |
| 301 | patches with the proper threading. If you have a long series, though, and | 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 | creating exceptionally deep nesting. | 307 | creating exceptionally deep nesting. |
diff --git a/Documentation/development-process/6.Followthrough b/Documentation/development-process/6.Followthrough index a8fba3d83a8..41d324a9420 100644 --- a/Documentation/development-process/6.Followthrough +++ b/Documentation/development-process/6.Followthrough | |||
| @@ -66,6 +66,11 @@ be easy to become blinded by your own solution to a problem to the point | |||
| 66 | that you don't realize that something is fundamentally wrong or, perhaps, | 66 | that you don't realize that something is fundamentally wrong or, perhaps, |
| 67 | you're not even solving the right problem. | 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 | One fatal mistake is to ignore review comments in the hope that they will | 74 | One fatal mistake is to ignore review comments in the hope that they will |
| 70 | go away. They will not go away. If you repost code without having | 75 | go away. They will not go away. If you repost code without having |
| 71 | responded to the comments you got the time before, you're likely to find | 76 | responded to the comments you got the time before, you're likely to find |
| @@ -100,7 +105,7 @@ entry into a subsystem maintainer's tree. How that works varies from one | |||
| 100 | subsystem to the next; each maintainer has his or her own way of doing | 105 | subsystem to the next; each maintainer has his or her own way of doing |
| 101 | things. In particular, there may be more than one tree - one, perhaps, | 106 | things. In particular, there may be more than one tree - one, perhaps, |
| 102 | dedicated to patches planned for the next merge window, and another for | 107 | dedicated to patches planned for the next merge window, and another for |
| 103 | longer-term work. | 108 | longer-term work. |
| 104 | 109 | ||
| 105 | For patches applying to areas for which there is no obvious subsystem tree | 110 | For patches applying to areas for which there is no obvious subsystem tree |
| 106 | (memory management patches, for example), the default tree often ends up | 111 | (memory management patches, for example), the default tree often ends up |
| @@ -109,11 +114,10 @@ through the -mm tree. | |||
| 109 | 114 | ||
| 110 | Inclusion into a subsystem tree can bring a higher level of visibility to a | 115 | Inclusion into a subsystem tree can bring a higher level of visibility to a |
| 111 | patch. Now other developers working with that tree will get the patch by | 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, | 117 | default. Subsystem trees typically feed linux-next as well, making their |
| 113 | making their contents visible to the development community as a whole. At | 118 | contents visible to the development community as a whole. At this point, |
| 114 | this point, there's a good chance that you will get more comments from a | 119 | there's a good chance that you will get more comments from a new set of |
| 115 | new set of reviewers; these comments need to be answered as in the previous | 120 | reviewers; these comments need to be answered as in the previous round. |
| 116 | round. | ||
| 117 | 121 | ||
| 118 | What may also happen at this point, depending on the nature of your patch, | 122 | What may also happen at this point, depending on the nature of your patch, |
| 119 | is that conflicts with work being done by others turn up. In the worst | 123 | is that conflicts with work being done by others turn up. In the worst |
diff --git a/Documentation/development-process/7.AdvancedTopics b/Documentation/development-process/7.AdvancedTopics index 837179447e1..26dc3fa196e 100644 --- a/Documentation/development-process/7.AdvancedTopics +++ b/Documentation/development-process/7.AdvancedTopics | |||
| @@ -119,7 +119,7 @@ can affect your ability to get trees pulled in the future. Quoting Linus: | |||
| 119 | to trust things *without* then having to go and check every | 119 | to trust things *without* then having to go and check every |
| 120 | individual change by hand. | 120 | individual change by hand. |
| 121 | 121 | ||
| 122 | (http://lwn.net/Articles/224135/). | 122 | (http://lwn.net/Articles/224135/). |
| 123 | 123 | ||
| 124 | To avoid this kind of situation, ensure that all patches within a given | 124 | To avoid this kind of situation, ensure that all patches within a given |
| 125 | branch stick closely to the associated topic; a "driver fixes" branch | 125 | branch stick closely to the associated topic; a "driver fixes" branch |
| @@ -138,7 +138,7 @@ When requesting a pull, be sure to give all the relevant information: where | |||
| 138 | your tree is, what branch to pull, and what changes will result from the | 138 | your tree is, what branch to pull, and what changes will result from the |
| 139 | pull. The git request-pull command can be helpful in this regard; it will | 139 | pull. The git request-pull command can be helpful in this regard; it will |
| 140 | format the request as other developers expect, and will also check to be | 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 | 7.2: REVIEWING PATCHES | 144 | 7.2: REVIEWING PATCHES |
