Merge branch 'topic/fix/hda' into for-linus
[linux-2.6] / Documentation / development-process / 2.Process
1 2: HOW THE DEVELOPMENT PROCESS WORKS
2
3 Linux kernel development in the early 1990's was a pretty loose affair,
4 with relatively small numbers of users and developers involved.  With a
5 user base in the millions and with some 2,000 developers involved over the
6 course of one year, the kernel has since had to evolve a number of
7 processes to keep development happening smoothly.  A solid understanding of
8 how the process works is required in order to be an effective part of it.
9
10
11 2.1: THE BIG PICTURE
12
13 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
15 release history looks like this:
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
24
25 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
27 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
29 rolling development model which is continually integrating major changes.
30
31 A relatively straightforward discipline is followed with regard to the
32 merging of patches for each release.  At the beginning of each development
33 cycle, the "merge window" is said to be open.  At that time, code which is
34 deemed to be sufficiently stable (and which is accepted by the development
35 community) is merged into the mainline kernel.  The bulk of changes for a
36 new development cycle (and all of the major changes) will be merged during
37 this time, at a rate approaching 1,000 changes ("patches," or "changesets")
38 per day.
39
40 (As an aside, it is worth noting that the changes integrated during the
41 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
43 detail later on).
44
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.
52
53 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
55 allowed, but such occasions are rare; developers who try to merge new
56 features outside of the merge window tend to get an unfriendly reception.
57 As a general rule, if you miss the merge window for a given feature, the
58 best thing to do is to wait for the next development cycle.  (An occasional
59 exception is made for drivers for previously-unsupported hardware; if they
60 touch no in-tree code, they cannot cause regressions and should be safe to
61 add at any time).
62
63 As fixes make their way into the mainline, the patch rate will slow over
64 time.  Linus releases new -rc kernels about once a week; a normal series
65 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.
67 At that point the whole process starts over again.
68
69 As an example, here is how the 2.6.25 development cycle went (all dates in
70 2008): 
71
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
83
84 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
86 regressions from previous releases.  No bugs are welcome, but those which
87 break systems which worked in the past are considered to be especially
88 serious.  For this reason, patches which cause regressions are looked upon
89 unfavorably and are quite likely to be reverted during the stabilization
90 period. 
91
92 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
94 achieve; there are just too many variables in a project of this size.
95 There comes a point where delaying the final release just makes the problem
96 worse; the pile of changes waiting for the next merge window will grow
97 larger, creating even more regressions the next time around.  So most 2.6.x
98 kernels go out with a handful of known regressions though, hopefully, none
99 of them are serious.
100
101 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:
108
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
118
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.
122
123
124 2.2: THE LIFECYCLE OF A PATCH
125
126 Patches do not go directly from the developer's keyboard into the mainline
127 kernel.  There is, instead, a somewhat involved (if somewhat informal)
128 process designed to ensure that each patch is reviewed for quality and that
129 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
131 and controversial changes, go on for years.  Much developer frustration
132 comes from a lack of understanding of this process or from attempts to
133 circumvent it.  
134
135 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
137 describes the process in a somewhat idealized way.  A much more detailed
138 treatment will come in later sections.
139
140 The stages that a patch goes through are, generally:
141
142  - Design.  This is where the real requirements for the patch - and the way
143    those requirements will be met - are laid out.  Design work is often
144    done without involving the community, but it is better to do this work
145    in the open if at all possible; it can save a lot of time redesigning
146    things later.
147
148  - Early review.  Patches are posted to the relevant mailing list, and
149    developers on that list reply with any comments they may have.  This
150    process should turn up any major problems with a patch if all goes
151    well.
152
153  - Wider review.  When the patch is getting close to ready for mainline
154    inclusion, it will be accepted by a relevant subsystem maintainer -
155    though this acceptance is not a guarantee that the patch will make it
156    all the way to the mainline.  The patch will show up in the maintainer's
157    subsystem tree and into the staging trees (described below).  When the
158    process works, this step leads to more extensive review of the patch and
159    the discovery of any problems resulting from the integration of this
160    patch with work being done by others.
161
162  - Merging into the mainline.  Eventually, a successful patch will be
163    merged into the mainline repository managed by Linus Torvalds.  More
164    comments and/or problems may surface at this time; it is important that
165    the developer be responsive to these and fix any issues which arise.
166
167  - Stable release.  The number of users potentially affected by the patch
168    is now large, so, once again, new problems may arise.
169
170  - Long-term maintenance.  While it is certainly possible for a developer
171    to forget about code after merging it, that sort of behavior tends to
172    leave a poor impression in the development community.  Merging code
173    eliminates some of the maintenance burden, in that others will fix
174    problems caused by API changes.  But the original developer should
175    continue to take responsibility for the code if it is to remain useful
176    in the longer term.
177
178 One of the largest mistakes made by kernel developers (or their employers)
179 is to try to cut the process down to a single "merging into the mainline"
180 step.  This approach invariably leads to frustration for everybody
181 involved.
182
183
184 2.3: HOW PATCHES GET INTO THE KERNEL
185
186 There is exactly one person who can merge patches into the mainline kernel
187 repository: Linus Torvalds.  But, of the over 12,000 patches which went
188 into the 2.6.25 kernel, only 250 (around 2%) were directly chosen by Linus
189 himself.  The kernel project has long since grown to a size where no single
190 developer could possibly inspect and select every patch unassisted.  The
191 way the kernel developers have addressed this growth is through the use of
192 a lieutenant system built around a chain of trust.
193
194 The kernel code base is logically broken down into a set of subsystems:
195 networking, specific architecture support, memory management, video
196 devices, etc.  Most subsystems have a designated maintainer, a developer
197 who has overall responsibility for the code within that subsystem.  These
198 subsystem maintainers are the gatekeepers (in a loose way) for the portion
199 of the kernel they manage; they are the ones who will (usually) accept a
200 patch for inclusion into the mainline kernel.
201
202 Subsystem maintainers each manage their own version of the kernel source
203 tree, usually (but certainly not always) using the git source management
204 tool.  Tools like git (and related tools like quilt or mercurial) allow
205 maintainers to track a list of patches, including authorship information
206 and other metadata.  At any given time, the maintainer can identify which
207 patches in his or her repository are not found in the mainline.
208
209 When the merge window opens, top-level maintainers will ask Linus to "pull"
210 the patches they have selected for merging from their repositories.  If
211 Linus agrees, the stream of patches will flow up into his repository,
212 becoming part of the mainline kernel.  The amount of attention that Linus
213 pays to specific patches received in a pull operation varies.  It is clear
214 that, sometimes, he looks quite closely.  But, as a general rule, Linus
215 trusts the subsystem maintainers to not send bad patches upstream.
216
217 Subsystem maintainers, in turn, can pull patches from other maintainers.
218 For example, the networking tree is built from patches which accumulated
219 first in trees dedicated to network device drivers, wireless networking,
220 etc.  This chain of repositories can be arbitrarily long, though it rarely
221 exceeds two or three links.  Since each maintainer in the chain trusts
222 those managing lower-level trees, this process is known as the "chain of
223 trust." 
224
225 Clearly, in a system like this, getting patches into the kernel depends on
226 finding the right maintainer.  Sending patches directly to Linus is not
227 normally the right way to go.
228
229
230 2.4: STAGING TREES
231
232 The chain of subsystem trees guides the flow of patches into the kernel,
233 but it also raises an interesting question: what if somebody wants to look
234 at all of the patches which are being prepared for the next merge window?
235 Developers will be interested in what other changes are pending to see
236 whether there are any conflicts to worry about; a patch which changes a
237 core kernel function prototype, for example, will conflict with any other
238 patches which use the older form of that function.  Reviewers and testers
239 want access to the changes in their integrated form before all of those
240 changes land in the mainline kernel.  One could pull changes from all of
241 the interesting subsystem trees, but that would be a big and error-prone
242 job.
243
244 The answer comes in the form of staging trees, where subsystem trees are
245 collected for testing and review.  The older of these trees, maintained by
246 Andrew Morton, is called "-mm" (for memory management, which is how it got
247 started).  The -mm tree integrates patches from a long list of subsystem
248 trees; it also has some patches aimed at helping with debugging.  
249
250 Beyond that, -mm contains a significant collection of patches which have
251 been selected by Andrew directly.  These patches may have been posted on a
252 mailing list, or they may apply to a part of the kernel for which there is
253 no designated subsystem tree.  As a result, -mm operates as a sort of
254 subsystem tree of last resort; if there is no other obvious path for a
255 patch into the mainline, it is likely to end up in -mm.  Miscellaneous
256 patches which accumulate in -mm will eventually either be forwarded on to
257 an appropriate subsystem tree or be sent directly to Linus.  In a typical
258 development cycle, approximately 10% of the patches going into the mainline
259 get there via -mm.
260
261 The current -mm patch can always be found from the front page of
262
263         http://kernel.org/
264
265 Those who want to see the current state of -mm can get the "-mm of the
266 moment" tree, found at:
267
268         http://userweb.kernel.org/~akpm/mmotm/
269
270 Use of the MMOTM tree is likely to be a frustrating experience, though;
271 there is a definite chance that it will not even compile.
272
273 The other staging tree, started more recently, is linux-next, maintained by
274 Stephen Rothwell.  The linux-next tree is, by design, a snapshot of what
275 the mainline is expected to look like after the next merge window closes.
276 Linux-next trees are announced on the linux-kernel and linux-next mailing
277 lists when they are assembled; they can be downloaded from:
278
279         http://www.kernel.org/pub/linux/kernel/people/sfr/linux-next/
280
281 Some information about linux-next has been gathered at:
282
283         http://linux.f-seidel.de/linux-next/pmwiki/
284
285 How the linux-next tree will fit into the development process is still
286 changing.  As of this writing, the first full development cycle involving
287 linux-next (2.6.26) is coming to an end; thus far, it has proved to be a
288 valuable resource for finding and fixing integration problems before the
289 beginning of the merge window.  See http://lwn.net/Articles/287155/ for
290 more information on how linux-next has worked to set up the 2.6.27 merge
291 window.
292
293 Some developers have begun to suggest that linux-next should be used as the
294 target for future development as well.  The linux-next tree does tend to be
295 far ahead of the mainline and is more representative of the tree into which
296 any new work will be merged.  The downside to this idea is that the
297 volatility of linux-next tends to make it a difficult development target.
298 See http://lwn.net/Articles/289013/ for more information on this topic, and
299 stay tuned; much is still in flux where linux-next is involved.
300
301
302 2.5: TOOLS
303
304 As can be seen from the above text, the kernel development process depends
305 heavily on the ability to herd collections of patches in various
306 directions.  The whole thing would not work anywhere near as well as it
307 does without suitably powerful tools.  Tutorials on how to use these tools
308 are well beyond the scope of this document, but there is space for a few
309 pointers.
310
311 By far the dominant source code management system used by the kernel
312 community is git.  Git is one of a number of distributed version control
313 systems being developed in the free software community.  It is well tuned
314 for kernel development, in that it performs quite well when dealing with
315 large repositories and large numbers of patches.  It also has a reputation
316 for being difficult to learn and use, though it has gotten better over
317 time.  Some sort of familiarity with git is almost a requirement for kernel
318 developers; even if they do not use it for their own work, they'll need git
319 to keep up with what other developers (and the mainline) are doing.
320
321 Git is now packaged by almost all Linux distributions.  There is a home
322 page at 
323
324         http://git.or.cz/
325
326 That page has pointers to documentation and tutorials.  One should be
327 aware, in particular, of the Kernel Hacker's Guide to git, which has
328 information specific to kernel development:
329
330         http://linux.yyz.us/git-howto.html
331
332 Among the kernel developers who do not use git, the most popular choice is
333 almost certainly Mercurial:
334
335         http://www.selenic.com/mercurial/
336
337 Mercurial shares many features with git, but it provides an interface which
338 many find easier to use.
339
340 The other tool worth knowing about is Quilt:
341
342         http://savannah.nongnu.org/projects/quilt/
343
344 Quilt is a patch management system, rather than a source code management
345 system.  It does not track history over time; it is, instead, oriented
346 toward tracking a specific set of changes against an evolving code base.
347 Some major subsystem maintainers use quilt to manage patches intended to go
348 upstream.  For the management of certain kinds of trees (-mm, for example),
349 quilt is the best tool for the job.
350
351
352 2.6: MAILING LISTS
353
354 A great deal of Linux kernel development work is done by way of mailing
355 lists.  It is hard to be a fully-functioning member of the community
356 without joining at least one list somewhere.  But Linux mailing lists also
357 represent a potential hazard to developers, who risk getting buried under a
358 load of electronic mail, running afoul of the conventions used on the Linux
359 lists, or both.
360
361 Most kernel mailing lists are run on vger.kernel.org; the master list can
362 be found at:
363
364         http://vger.kernel.org/vger-lists.html
365
366 There are lists hosted elsewhere, though; a number of them are at
367 lists.redhat.com.
368
369 The core mailing list for kernel development is, of course, linux-kernel.
370 This list is an intimidating place to be; volume can reach 500 messages per
371 day, the amount of noise is high, the conversation can be severely
372 technical, and participants are not always concerned with showing a high
373 degree of politeness.  But there is no other place where the kernel
374 development community comes together as a whole; developers who avoid this
375 list will miss important information.
376
377 There are a few hints which can help with linux-kernel survival:
378
379 - Have the list delivered to a separate folder, rather than your main
380   mailbox.  One must be able to ignore the stream for sustained periods of
381   time.
382
383 - Do not try to follow every conversation - nobody else does.  It is
384   important to filter on both the topic of interest (though note that
385   long-running conversations can drift away from the original subject
386   without changing the email subject line) and the people who are
387   participating.  
388
389 - Do not feed the trolls.  If somebody is trying to stir up an angry
390   response, ignore them.
391
392 - When responding to linux-kernel email (or that on other lists) preserve
393   the Cc: header for all involved.  In the absence of a strong reason (such
394   as an explicit request), you should never remove recipients.  Always make
395   sure that the person you are responding to is in the Cc: list.  This
396   convention also makes it unnecessary to explicitly ask to be copied on
397   replies to your postings.
398
399 - Search the list archives (and the net as a whole) before asking
400   questions.  Some developers can get impatient with people who clearly
401   have not done their homework.
402
403 - Avoid top-posting (the practice of putting your answer above the quoted
404   text you are responding to).  It makes your response harder to read and
405   makes a poor impression.
406
407 - Ask on the correct mailing list.  Linux-kernel may be the general meeting
408   point, but it is not the best place to find developers from all
409   subsystems.
410
411 The last point - finding the correct mailing list - is a common place for
412 beginning developers to go wrong.  Somebody who asks a networking-related
413 question on linux-kernel will almost certainly receive a polite suggestion
414 to ask on the netdev list instead, as that is the list frequented by most
415 networking developers.  Other lists exist for the SCSI, video4linux, IDE,
416 filesystem, etc. subsystems.  The best place to look for mailing lists is
417 in the MAINTAINERS file packaged with the kernel source.
418
419
420 2.7: GETTING STARTED WITH KERNEL DEVELOPMENT
421
422 Questions about how to get started with the kernel development process are
423 common - from both individuals and companies.  Equally common are missteps
424 which make the beginning of the relationship harder than it has to be.
425
426 Companies often look to hire well-known developers to get a development
427 group started.  This can, in fact, be an effective technique.  But it also
428 tends to be expensive and does not do much to grow the pool of experienced
429 kernel developers.  It is possible to bring in-house developers up to speed
430 on Linux kernel development, given the investment of a bit of time.  Taking
431 this time can endow an employer with a group of developers who understand
432 the kernel and the company both, and who can help to train others as well.
433 Over the medium term, this is often the more profitable approach.
434
435 Individual developers are often, understandably, at a loss for a place to
436 start.  Beginning with a large project can be intimidating; one often wants
437 to test the waters with something smaller first.  This is the point where
438 some developers jump into the creation of patches fixing spelling errors or
439 minor coding style issues.  Unfortunately, such patches create a level of
440 noise which is distracting for the development community as a whole, so,
441 increasingly, they are looked down upon.  New developers wishing to
442 introduce themselves to the community will not get the sort of reception
443 they wish for by these means.
444
445 Andrew Morton gives this advice for aspiring kernel developers
446
447         The #1 project for all kernel beginners should surely be "make sure
448         that the kernel runs perfectly at all times on all machines which
449         you can lay your hands on".  Usually the way to do this is to work
450         with others on getting things fixed up (this can require
451         persistence!) but that's fine - it's a part of kernel development.
452
453 (http://lwn.net/Articles/283982/).
454
455 In the absence of obvious problems to fix, developers are advised to look
456 at the current lists of regressions and open bugs in general.  There is
457 never any shortage of issues in need of fixing; by addressing these issues,
458 developers will gain experience with the process while, at the same time,
459 building respect with the rest of the development community.