leandrof/linux
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Documentation: bring process docs up to date

Browse Source 
The guide to the kernel dev process documentation, for example, contains
references to older kernels and their timelines. In addition, one of the
"long term support kernels" listed have since reached EOL, and a new one
has been named. This patch brings information/tables up to date.

Additionally, some very trivial grammatical errors, unclear sentences,
and potentially unsavory diction have been edited.

Signed-off-by: Tony Fischetti <tony.fischetti@gmail.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Tony Fischetti 2020-02-16 19:08:26 -05:00 committed by Jonathan Corbet
parent dff2c2e69f
commit fb0e0ffe7f
3 changed files with 73 additions and 70 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

108
Documentation/process/2.Process.rst
View File

@ -18,18 +18,18 @@ major kernel release happening every two or three months. The recent
release history looks like this: release history looks like this:
====== ================= ====== =================
4.11 April 30, 2017 5.0 March 3, 2019
4.12 July 2, 2017 5.1 May 5, 2019
4.13 September 3, 2017 5.2 July 7, 2019
4.14 November 12, 2017 5.3 September 15, 2019
4.15 January 28, 2018 5.4 November 24, 2019
4.16 April 1, 2018 5.5 January 6, 2020
====== ================= ====== =================
Every 4.x release is a major kernel release with new features, internal Every 5.x release is a major kernel release with new features, internal
API changes, and more. A typical 4.x release contain about 13,000 API changes, and more. A typical release can contain about 13,000
changesets with changes to several hundred thousand lines of code. 4.x is changesets with changes to several hundred thousand lines of code. 5.x is
thus the leading edge of Linux kernel development; the kernel uses a the leading edge of Linux kernel development; the kernel uses a
rolling development model which is continually integrating major changes. rolling development model which is continually integrating major changes.
A relatively straightforward discipline is followed with regard to the A relatively straightforward discipline is followed with regard to the
@ -48,9 +48,9 @@ detail later on).
The merge window lasts for approximately two weeks. At the end of this 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 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, first of the "rc" kernels. For the kernel which is destined to be 5.6,
for example, the release which happens at the end of the merge window will 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 be called 5.6-rc1. The -rc1 release is the signal that the time to
merge new features has passed, and that the time to stabilize the next merge new features has passed, and that the time to stabilize the next
kernel has begun. kernel has begun.
@ -67,22 +67,23 @@ add at any time).
As fixes make their way into the mainline, the patch rate will slow over As fixes make their way into the mainline, the patch rate will slow over
time. Linus releases new -rc kernels about once a week; a normal series time. Linus releases new -rc kernels about once a week; a normal series
will get up to somewhere between -rc6 and -rc9 before the kernel is will get up to somewhere between -rc6 and -rc9 before the kernel is
considered to be sufficiently stable and the final 2.6.x release is made. considered to be sufficiently stable and the final release is made.
At that point the whole process starts over again. At that point the whole process starts over again.
As an example, here is how the 4.16 development cycle went (all dates in As an example, here is how the 5.4 development cycle went (all dates in
2018): 2019):
============== =============================== ============== ===============================
January 28 4.15 stable release September 15 5.3 stable release
February 11 4.16-rc1, merge window closes September 30 5.4-rc1, merge window closes
February 18 4.16-rc2 October 6 5.4-rc2
February 25 4.16-rc3 October 13 5.4-rc3
March 4 4.16-rc4 October 20 5.4-rc4
March 11 4.16-rc5 October 27 5.4-rc5
March 18 4.16-rc6 November 3 5.4-rc6
March 25 4.16-rc7 November 10 5.4-rc7
April 1 4.16 stable release November 17 5.4-rc8
November 24 5.4 stable release
============== =============================== ============== ===============================
How do the developers decide when to close the development cycle and create How do the developers decide when to close the development cycle and create
@ -98,43 +99,44 @@ release is made. In the real world, this kind of perfection is hard to
achieve; there are just too many variables in a project of this size. achieve; there are just too many variables in a project of this size.
There comes a point where delaying the final release just makes the problem There comes a point where delaying the final release just makes the problem
worse; the pile of changes waiting for the next merge window will grow worse; the pile of changes waiting for the next merge window will grow
larger, creating even more regressions the next time around. So most 4.x larger, creating even more regressions the next time around. So most 5.x
kernels go out with a handful of known regressions though, hopefully, none kernels go out with a handful of known regressions though, hopefully, none
of them are serious. of them are serious.
Once a stable release is made, its ongoing maintenance is passed off to the Once a stable release is made, its ongoing maintenance is passed off to the
"stable team," currently consisting of Greg Kroah-Hartman. The stable team "stable team," currently Greg Kroah-Hartman. The stable team will release
will release occasional updates to the stable release using the 4.x.y occasional updates to the stable release using the 5.x.y numbering scheme.
numbering scheme. To be considered for an update release, a patch must (1) To be considered for an update release, a patch must (1) fix a significant
fix a significant bug, and (2) already be merged into the mainline for the bug, and (2) already be merged into the mainline for the next development
next development kernel. Kernels will typically receive stable updates for kernel. Kernels will typically receive stable updates for a little more
a little more than one development cycle past their initial release. So, than one development cycle past their initial release. So, for example, the
for example, the 4.13 kernel's history looked like: 5.2 kernel's history looked like this (all dates in 2019):
============== =============================== ============== ===============================
September 3 4.13 stable release September 15 5.2 stable release
September 13 4.13.1 July 14 5.2.1
September 20 4.13.2 July 21 5.2.2
September 27 4.13.3 July 26 5.2.3
October 5 4.13.4 July 28 5.2.4
October 12 4.13.5 July 31 5.2.5
... ... ... ...
November 24 4.13.16 October 11 5.2.21
============== =============================== ============== ===============================
4.13.16 was the final stable update of the 4.13 release. 5.2.21 was the final stable update of the 5.2 release.
Some kernels are designated "long term" kernels; they will receive support Some kernels are designated "long term" kernels; they will receive support
for a longer period. As of this writing, the current long term kernels for a longer period. As of this writing, the current long term kernels
and their maintainers are: and their maintainers are:
====== ====================== ============================== ====== ================================ =======================
3.16 Ben Hutchings (very long-term stable kernel) 3.16 Ben Hutchings (very long-term kernel)
4.1 Sasha Levin 4.4 Greg Kroah-Hartman & Sasha Levin (very long-term kernel)
4.4 Greg Kroah-Hartman (very long-term stable kernel) 4.9 Greg Kroah-Hartman & Sasha Levin
4.9 Greg Kroah-Hartman 4.14 Greg Kroah-Hartman & Sasha Levin
4.14 Greg Kroah-Hartman 4.19 Greg Kroah-Hartman & Sasha Levin
====== ====================== ============================== 5.4 Greg Kroah-Hartman & Sasha Levin
====== ================================ =======================
The selection of a kernel for long-term support is purely a matter of a The selection of a kernel for long-term support is purely a matter of a
maintainer having the need and the time to maintain that release. There maintainer having the need and the time to maintain that release. There
@ -215,12 +217,12 @@ How patches get into the Kernel
------------------------------- -------------------------------
There is exactly one person who can merge patches into the mainline kernel There is exactly one person who can merge patches into the mainline kernel
repository: Linus Torvalds. But, of the over 9,500 patches which went repository: Linus Torvalds. But, for example, of the over 9,500 patches
into the 2.6.38 kernel, only 112 (around 1.3%) were directly chosen by Linus which went into the 2.6.38 kernel, only 112 (around 1.3%) were directly
himself. The kernel project has long since grown to a size where no single chosen by Linus himself. The kernel project has long since grown to a size
developer could possibly inspect and select every patch unassisted. The where no single developer could possibly inspect and select every patch
way the kernel developers have addressed this growth is through the use of unassisted. The way the kernel developers have addressed this growth is
a lieutenant system built around a chain of trust. through the use of a lieutenant system built around a chain of trust.
The kernel code base is logically broken down into a set of subsystems: The kernel code base is logically broken down into a set of subsystems:
networking, specific architecture support, memory management, video networking, specific architecture support, memory management, video

18
Documentation/process/coding-style.rst
View File

@ -284,9 +284,9 @@ context lines.
4) Naming 4) Naming
--------- ---------
C is a Spartan language, and so should your naming be. Unlike Modula-2 C is a Spartan language, and your naming conventions should follow suit.
and Pascal programmers, C programmers do not use cute names like Unlike Modula-2 and Pascal programmers, C programmers do not use cute
ThisVariableIsATemporaryCounter. A C programmer would call that names like ThisVariableIsATemporaryCounter. A C programmer would call that
variable ``tmp``, which is much easier to write, and not the least more variable ``tmp``, which is much easier to write, and not the least more
difficult to understand. difficult to understand.
@ -300,9 +300,9 @@ that counts the number of active users, you should call that
``count_active_users()`` or similar, you should **not** call it ``cntusr()``. ``count_active_users()`` or similar, you should **not** call it ``cntusr()``.
Encoding the type of a function into the name (so-called Hungarian Encoding the type of a function into the name (so-called Hungarian
notation) is brain damaged - the compiler knows the types anyway and can notation) is asinine - the compiler knows the types anyway and can check
check those, and it only confuses the programmer. No wonder MicroSoft those, and it only confuses the programmer. No wonder Microsoft makes buggy
makes buggy programs. programs.
LOCAL variable names should be short, and to the point. If you have LOCAL variable names should be short, and to the point. If you have
some random integer loop counter, it should probably be called ``i``. some random integer loop counter, it should probably be called ``i``.
@ -806,9 +806,9 @@ covers RTL which is used frequently with assembly language in the kernel.
---------------------------- ----------------------------
Kernel developers like to be seen as literate. Do mind the spelling Kernel developers like to be seen as literate. Do mind the spelling
of kernel messages to make a good impression. Do not use crippled of kernel messages to make a good impression. Do not use incorrect
words like ``dont``; use ``do not`` or ``don't`` instead. Make the messages contractions like ``dont``; use ``do not`` or ``don't`` instead. Make the
concise, clear, and unambiguous. messages concise, clear, and unambiguous.
Kernel messages do not have to be terminated with a period. Kernel messages do not have to be terminated with a period.

17
Documentation/process/howto.rst
View File

@ -243,10 +243,10 @@ branches. These different branches are:
Mainline tree Mainline tree
~~~~~~~~~~~~~ ~~~~~~~~~~~~~
Mainline tree are maintained by Linus Torvalds, and can be found at The mainline tree is maintained by Linus Torvalds, and can be found at
https://kernel.org or in the repo. Its development process is as follows: https://kernel.org or in the repo. Its development process is as follows:
- As soon as a new kernel is released a two weeks window is open, - As soon as a new kernel is released a two week window is open,
during this period of time maintainers can submit big diffs to during this period of time maintainers can submit big diffs to
Linus, usually the patches that have already been included in the Linus, usually the patches that have already been included in the
linux-next for a few weeks. The preferred way to submit big changes linux-next for a few weeks. The preferred way to submit big changes
@ -281,8 +281,9 @@ Various stable trees with multiple major numbers
Kernels with 3-part versions are -stable kernels. They contain Kernels with 3-part versions are -stable kernels. They contain
relatively small and critical fixes for security problems or significant relatively small and critical fixes for security problems or significant
regressions discovered in a given major mainline release, with the first regressions discovered in a given major mainline release. Each release
2-part of version number are the same correspondingly. in a major stable series increments the third part of the version
number, keeping the first two parts the same.
This is the recommended branch for users who want the most recent stable This is the recommended branch for users who want the most recent stable
kernel and are not interested in helping test development/experimental kernel and are not interested in helping test development/experimental
@ -359,10 +360,10 @@ Managing bug reports
One of the best ways to put into practice your hacking skills is by fixing One of the best ways to put into practice your hacking skills is by fixing
bugs reported by other people. Not only you will help to make the kernel bugs reported by other people. Not only you will help to make the kernel
more stable, you'll learn to fix real world problems and you will improve more stable, but you'll also learn to fix real world problems and you will
your skills, and other developers will be aware of your presence. Fixing improve your skills, and other developers will be aware of your presence.
bugs is one of the best ways to get merits among other developers, because Fixing bugs is one of the best ways to get merits among other developers,
not many people like wasting time fixing other people's bugs. because not many people like wasting time fixing other people's bugs.
To work in the already reported bug reports, go to https://bugzilla.kernel.org. To work in the already reported bug reports, go to https://bugzilla.kernel.org.