Documentation/process/2.Process.rst

6 Linux kernel development in the early 1990's was a pretty loose affair,
8 user base in the millions and with some 2,000 developers involved over the
9 course of one year, the kernel has since had to evolve a number of
11 how the process works is required in order to be an effective part of it.
14 ---------------
16 The kernel developers use a loosely time-based release process, with a new
17 major kernel release happening every two or three months.  The recent
29 Every 5.x release is a major kernel release with new features, internal
32 the leading edge of Linux kernel development; the kernel uses a
39 community) is merged into the mainline kernel.  The bulk of changes for a
46 and staged ahead of time.  How that process works will be described in
51 first of the "rc" kernels.  For the kernel which is destined to be 5.6,
53 be called 5.6-rc1.  The -rc1 release is the signal that the time to
55 kernel has begun.
63 exception is made for drivers for previously-unsupported hardware; if they
64 touch no in-tree code, they cannot cause regressions and should be safe to
68 time.  Linus releases new -rc kernels about once a week; a normal series
69 will get up to somewhere between -rc6 and -rc9 before the kernel is
73 As an example, here is how the 5.4 development cycle went (all dates in
78 	September 30	5.4-rc1, merge window closes
79 	October 6	5.4-rc2
80 	October 13	5.4-rc3
81 	October 20	5.4-rc4
82 	October 27	5.4-rc5
83 	November 3	5.4-rc6
84 	November 10	5.4-rc7
85 	November 17	5.4-rc8
92 break systems which worked in the past are considered to be especially
98 release is made.  In the real world, this kind of perfection is hard to
99 achieve; there are just too many variables in a project of this size.
107 "stable team," currently Greg Kroah-Hartman. The stable team will release
111 kernel. Kernels will typically receive stable updates for a little more
113 5.2 kernel's history looked like this (all dates in 2019):
133 	3.16	Ben Hutchings				(very long-term kernel)
134 	4.4	Greg Kroah-Hartman & Sasha Levin	(very long-term kernel)
135 	4.9	Greg Kroah-Hartman & Sasha Levin
136 	4.14	Greg Kroah-Hartman & Sasha Levin
137 	4.19	Greg Kroah-Hartman & Sasha Levin
138 	5.4	Greg Kroah-Hartman & Sasha Levin
141 The selection of a kernel for long-term support is purely a matter of a
143 are no known plans for long-term support for any specific upcoming
148 ------------------------
151 kernel.  There is, instead, a somewhat involved (if somewhat informal)
153 each patch implements a change which is desirable to have in the mainline.
154 This process can happen quickly for minor fixes, or, in the case of large
159 In the hopes of reducing that frustration, this document will describe how
160 a patch gets into the kernel.  What follows below is an introduction which
161 describes the process in a somewhat idealized way.  A much more detailed
162 treatment will come in later sections.
166  - Design.  This is where the real requirements for the patch - and the way
167    those requirements will be met - are laid out.  Design work is often
169    in the open if at all possible; it can save a lot of time redesigning
172  - Early review.  Patches are posted to the relevant mailing list, and
177  - Wider review.  When the patch is getting close to ready for mainline
178    inclusion, it should be accepted by a relevant subsystem maintainer -
180    all the way to the mainline.  The patch will show up in the maintainer's
181    subsystem tree and into the -next trees (described below).  When the
186 -  Please note that most maintainers also have day jobs, so merging
192    in updating the patch to the current kernel so that it applies cleanly
195  - Merging into the mainline.  Eventually, a successful patch will be
200  - Stable release.  The number of users potentially affected by the patch
203  - Long-term maintenance.  While it is certainly possible for a developer
205    leave a poor impression in the development community.  Merging code
206    eliminates some of the maintenance burden, in that others will fix
209    in the longer term.
211 One of the largest mistakes made by kernel developers (or their employers)
216 How patches get into the Kernel
217 -------------------------------
219 There is exactly one person who can merge patches into the mainline kernel
221 which went into the 2.6.38 kernel, only 112 (around 1.3%) were directly
222 chosen by Linus himself. The kernel project has long since grown to a size
224 unassisted. The way the kernel developers have addressed this growth is
227 The kernel code base is logically broken down into a set of subsystems:
231 subsystem maintainers are the gatekeepers (in a loose way) for the portion
232 of the kernel they manage; they are the ones who will (usually) accept a
233 patch for inclusion into the mainline kernel.
235 Subsystem maintainers each manage their own version of the kernel source
240 patches in his or her repository are not found in the mainline.
242 When the merge window opens, top-level maintainers will ask Linus to "pull"
245 becoming part of the mainline kernel.  The amount of attention that Linus
246 pays to specific patches received in a pull operation varies.  It is clear
250 Subsystem maintainers, in turn, can pull patches from other maintainers.
252 first in trees dedicated to network device drivers, wireless networking,
254 exceeds two or three links.  Since each maintainer in the chain trusts
255 those managing lower-level trees, this process is known as the "chain of
258 Clearly, in a system like this, getting patches into the kernel depends on
264 ----------
266 The chain of subsystem trees guides the flow of patches into the kernel,
269 Developers will be interested in what other changes are pending to see
271 core kernel function prototype, for example, will conflict with any other
273 want access to the changes in their integrated form before all of those
274 changes land in the mainline kernel.  One could pull changes from all of
275 the interesting subsystem trees, but that would be a big and error-prone
278 The answer comes in the form of -next trees, where subsystem trees are
280 Andrew Morton, is called "-mm" (for memory management, which is how it got
281 started).  The -mm tree integrates patches from a long list of subsystem
284 Beyond that, -mm contains a significant collection of patches which have
286 mailing list, or they may apply to a part of the kernel for which there is
287 no designated subsystem tree.  As a result, -mm operates as a sort of
289 patch into the mainline, it is likely to end up in -mm.  Miscellaneous
290 patches which accumulate in -mm will eventually either be forwarded on to
291 an appropriate subsystem tree or be sent directly to Linus.  In a typical
292 development cycle, approximately 5-10% of the patches going into the
293 mainline get there via -mm.
295 The current -mm patch is available in the "mmotm" (-mm of the moment)
303 The primary tree for next-cycle patch merging is linux-next, maintained by
304 Stephen Rothwell.  The linux-next tree is, by design, a snapshot of what
306 Linux-next trees are announced on the linux-kernel and linux-next mailing
309 	https://www.kernel.org/pub/linux/kernel/next/
311 Linux-next has become an integral part of the kernel development process;
313 their way into linux-next some time before the merge window opens.
317 -------------
319 The kernel source tree contains the drivers/staging/ directory, where
320 many sub-directories for drivers or filesystems that are on their way to
321 being added to the kernel tree live.  They remain in drivers/staging while
323 kernel proper.  This is a way to keep track of drivers that aren't
324 up to Linux kernel coding or quality standards, but people may want to use
327 Greg Kroah-Hartman currently maintains the staging tree.  Drivers that
329 subdirectory in drivers/staging/.  Along with the driver source files, a
330 TODO file should be present in the directory as well.  The TODO file lists
331 the pending work that the driver needs for acceptance into the kernel
339 code in staging which is not seeing regular progress will eventually be
346 -----
348 As can be seen from the above text, the kernel development process depends
349 heavily on the ability to herd collections of patches in various
355 By far the dominant source code management system used by the kernel
357 systems being developed in the free software community.  It is well tuned
358 for kernel development, in that it performs quite well when dealing with
361 time.  Some sort of familiarity with git is almost a requirement for kernel
368 	https://git-scm.com/
372 Among the kernel developers who do not use git, the most popular choice is
388 upstream.  For the management of certain kinds of trees (-mm, for example),
393 -------------
395 A great deal of Linux kernel development work is done by way of mailing
396 lists.  It is hard to be a fully-functioning member of the community
402 Most kernel mailing lists are run on vger.kernel.org; the master list can
405 	http://vger.kernel.org/vger-lists.html
410 The core mailing list for kernel development is, of course, linux-kernel.
414 degree of politeness.  But there is no other place where the kernel
418 There are a few hints which can help with linux-kernel survival:
420 - Have the list delivered to a separate folder, rather than your main
424 - Do not try to follow every conversation - nobody else does.  It is
426   long-running conversations can drift away from the original subject
430 - Do not feed the trolls.  If somebody is trying to stir up an angry
433 - When responding to linux-kernel email (or that on other lists) preserve
434   the Cc: header for all involved.  In the absence of a strong reason (such
436   sure that the person you are responding to is in the Cc: list.  This
440 - Search the list archives (and the net as a whole) before asking
444 - Avoid top-posting (the practice of putting your answer above the quoted
448 - Ask on the correct mailing list.  Linux-kernel may be the general meeting
452 The last point - finding the correct mailing list - is a common place for
453 beginning developers to go wrong.  Somebody who asks a networking-related
454 question on linux-kernel will almost certainly receive a polite suggestion
458 in the MAINTAINERS file packaged with the kernel source.
461 Getting started with Kernel development
462 ---------------------------------------
464 Questions about how to get started with the kernel development process are
465 common - from both individuals and companies.  Equally common are missteps
468 Companies often look to hire well-known developers to get a development
469 group started.  This can, in fact, be an effective technique.  But it also
471 kernel developers.  It is possible to bring in-house developers up to speed
472 on Linux kernel development, given the investment of a bit of time.  Taking
474 the kernel and the company both, and who can help to train others as well.
487 Andrew Morton gives this advice for aspiring kernel developers
491 	The #1 project for all kernel beginners should surely be "make sure
492 	that the kernel runs perfectly at all times on all machines which
495 	persistence!) but that's fine - it's a part of kernel development.
499 In the absence of obvious problems to fix, developers are advised to look
500 at the current lists of regressions and open bugs in general.  There is
501 never any shortage of issues in need of fixing; by addressing these issues,