Commit | Line | Data |
---|---|---|
609d99a3 MCC |
1 | .. _stable_kernel_rules: |
2 | ||
5fe270a4 MCC |
3 | Everything you ever wanted to know about Linux -stable releases |
4 | =============================================================== | |
fc185d95 | 5 | |
e48e9909 JJ |
6 | Rules on what kind of patches are accepted, and which ones are not, into the |
7 | "-stable" tree: | |
fc185d95 GK |
8 | |
9 | - It must be obviously correct and tested. | |
84eb8d06 | 10 | - It cannot be bigger than 100 lines, with context. |
fc185d95 GK |
11 | - It must fix only one thing. |
12 | - It must fix a real bug that bothers people (not a, "This could be a | |
e48e9909 | 13 | problem..." type thing). |
fc185d95 GK |
14 | - It must fix a problem that causes a build error (but not for things |
15 | marked CONFIG_BROKEN), an oops, a hang, data corruption, a real | |
e48e9909 JJ |
16 | security issue, or some "oh, that's not good" issue. In short, something |
17 | critical. | |
8191e0d9 MG |
18 | - Serious issues as reported by a user of a distribution kernel may also |
19 | be considered if they fix a notable performance or interactivity issue. | |
20 | As these fixes are not as obvious and have a higher risk of a subtle | |
21 | regression they should only be submitted by a distribution kernel | |
22 | maintainer and include an addendum linking to a bugzilla entry if it | |
23 | exists and additional information on the user-visible impact. | |
79cd80a1 | 24 | - New device IDs and quirks are also accepted. |
e48e9909 JJ |
25 | - No "theoretical race condition" issues, unless an explanation of how the |
26 | race can be exploited is also provided. | |
84eb8d06 | 27 | - It cannot contain any "trivial" fixes in it (spelling changes, |
e48e9909 | 28 | whitespace cleanups, etc). |
dca22a63 | 29 | - It must follow the |
8c27ceff | 30 | :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` |
dca22a63 | 31 | rules. |
959fb1c5 | 32 | - It or an equivalent fix must already exist in Linus' tree (upstream). |
fc185d95 GK |
33 | |
34 | ||
5fe270a4 MCC |
35 | Procedure for submitting patches to the -stable tree |
36 | ---------------------------------------------------- | |
fc185d95 | 37 | |
615f3eea BS |
38 | .. note:: |
39 | ||
40 | Security patches should not be handled (solely) by the -stable review | |
dca22a63 | 41 | process but should follow the procedures in |
8c27ceff | 42 | :ref:`Documentation/admin-guide/security-bugs.rst <securitybugs>`. |
5de61e7a | 43 | |
5fe270a4 MCC |
44 | For all other submissions, choose one of the following procedures |
45 | ----------------------------------------------------------------- | |
5de61e7a | 46 | |
5fe270a4 MCC |
47 | .. _option_1: |
48 | ||
49 | Option 1 | |
50 | ******** | |
51 | ||
52 | To have the patch automatically included in the stable tree, add the tag | |
53 | ||
54 | .. code-block:: none | |
5de61e7a | 55 | |
5fa22429 | 56 | Cc: stable@vger.kernel.org |
5de61e7a | 57 | |
5fe270a4 MCC |
58 | in the sign-off area. Once the patch is merged it will be applied to |
59 | the stable tree without anything else needing to be done by the author | |
60 | or subsystem maintainer. | |
61 | ||
62 | .. _option_2: | |
5de61e7a | 63 | |
5fe270a4 MCC |
64 | Option 2 |
65 | ******** | |
5de61e7a | 66 | |
5fe270a4 MCC |
67 | After the patch has been merged to Linus' tree, send an email to |
68 | stable@vger.kernel.org containing the subject of the patch, the commit ID, | |
69 | why you think it should be applied, and what kernel version you wish it to | |
70 | be applied to. | |
5de61e7a | 71 | |
5fe270a4 | 72 | .. _option_3: |
5de61e7a | 73 | |
5fe270a4 MCC |
74 | Option 3 |
75 | ******** | |
bde1b294 | 76 | |
5fe270a4 MCC |
77 | Send the patch, after verifying that it follows the above rules, to |
78 | stable@vger.kernel.org. You must note the upstream commit ID in the | |
79 | changelog of your submission, as well as the kernel version you wish | |
80 | it to be applied to. | |
81 | ||
82 | :ref:`option_1` is **strongly** preferred, is the easiest and most common. | |
83 | :ref:`option_2` and :ref:`option_3` are more useful if the patch isn't deemed | |
84 | worthy at the time it is applied to a public git tree (for instance, because | |
85 | it deserves more regression testing first). :ref:`option_3` is especially | |
88d99e87 BS |
86 | useful if the original upstream patch needs to be backported (for example |
87 | the backport needs some special handling due to e.g. API changes). | |
5fe270a4 MCC |
88 | |
89 | Note that for :ref:`option_3`, if the patch deviates from the original | |
90 | upstream patch (for example because it had to be backported) this must be very | |
91 | clearly documented and justified in the patch description. | |
bde1b294 CD |
92 | |
93 | The upstream commit ID must be specified with a separate line above the commit | |
94 | text, like this: | |
95 | ||
5fe270a4 MCC |
96 | .. code-block:: none |
97 | ||
bde1b294 | 98 | commit <sha1> upstream. |
5de61e7a | 99 | |
b04c11c9 FV |
100 | Additionally, some patches submitted via :ref:`option_1` may have additional |
101 | patch prerequisites which can be cherry-picked. This can be specified in the | |
102 | following format in the sign-off area: | |
8e9b9362 | 103 | |
5fe270a4 MCC |
104 | .. code-block:: none |
105 | ||
2584f521 PG |
106 | Cc: <stable@vger.kernel.org> # 3.3.x: a1f84a3: sched: Check for idle |
107 | Cc: <stable@vger.kernel.org> # 3.3.x: 1b9508f: sched: Rate-limit newidle | |
108 | Cc: <stable@vger.kernel.org> # 3.3.x: fd21073: sched: Fix affinity logic | |
109 | Cc: <stable@vger.kernel.org> # 3.3.x | |
5fe270a4 MCC |
110 | Signed-off-by: Ingo Molnar <mingo@elte.hu> |
111 | ||
112 | The tag sequence has the meaning of: | |
113 | ||
114 | .. code-block:: none | |
8e9b9362 | 115 | |
8e9b9362 SAS |
116 | git cherry-pick a1f84a3 |
117 | git cherry-pick 1b9508f | |
118 | git cherry-pick fd21073 | |
119 | git cherry-pick <this commit> | |
120 | ||
fdc81b79 DD |
121 | Also, some patches may have kernel version prerequisites. This can be |
122 | specified in the following format in the sign-off area: | |
123 | ||
5fe270a4 MCC |
124 | .. code-block:: none |
125 | ||
cf903e9d | 126 | Cc: <stable@vger.kernel.org> # 3.3.x |
fdc81b79 | 127 | |
5fe270a4 MCC |
128 | The tag has the meaning of: |
129 | ||
130 | .. code-block:: none | |
131 | ||
fdc81b79 DD |
132 | git cherry-pick <this commit> |
133 | ||
5fe270a4 | 134 | For each "-stable" tree starting with the specified version. |
fdc81b79 | 135 | |
5de61e7a BN |
136 | Following the submission: |
137 | ||
e48e9909 JJ |
138 | - The sender will receive an ACK when the patch has been accepted into the |
139 | queue, or a NAK if the patch is rejected. This response might take a few | |
140 | days, according to the developer's schedules. | |
141 | - If accepted, the patch will be added to the -stable queue, for review by | |
46cdf871 | 142 | other developers and by the relevant subsystem maintainer. |
fc185d95 GK |
143 | |
144 | ||
5fe270a4 MCC |
145 | Review cycle |
146 | ------------ | |
fc185d95 | 147 | |
e48e9909 JJ |
148 | - When the -stable maintainers decide for a review cycle, the patches will be |
149 | sent to the review committee, and the maintainer of the affected area of | |
150 | the patch (unless the submitter is the maintainer of the area) and CC: to | |
151 | the linux-kernel mailing list. | |
152 | - The review committee has 48 hours in which to ACK or NAK the patch. | |
fc185d95 | 153 | - If the patch is rejected by a member of the committee, or linux-kernel |
e48e9909 JJ |
154 | members object to the patch, bringing up issues that the maintainers and |
155 | members did not realize, the patch will be dropped from the queue. | |
88d99e87 BS |
156 | - The ACKed patches will be posted again as part of release candidate (-rc) |
157 | to be tested by developers and testers. | |
158 | - Usually only one -rc release is made, however if there are any outstanding | |
159 | issues, some patches may be modified or dropped or additional patches may | |
160 | be queued. Additional -rc releases are then released and tested until no | |
161 | issues are found. | |
162 | - Responding to the -rc releases can be done on the mailing list by sending | |
163 | a "Tested-by:" email with any testing information desired. The "Tested-by:" | |
164 | tags will be collected and added to the release commit. | |
165 | - At the end of the review cycle, the new -stable release will be released | |
166 | containing all the queued and tested patches. | |
e48e9909 JJ |
167 | - Security patches will be accepted into the -stable tree directly from the |
168 | security kernel team, and not go through the normal review cycle. | |
fc185d95 GK |
169 | Contact the kernel security team for more details on this procedure. |
170 | ||
5fe270a4 MCC |
171 | Trees |
172 | ----- | |
2584f521 PG |
173 | |
174 | - The queues of patches, for both completed versions and in progress | |
175 | versions can be found at: | |
5fe270a4 | 176 | |
c1aa3871 | 177 | https://git.kernel.org/pub/scm/linux/kernel/git/stable/stable-queue.git |
5fe270a4 | 178 | |
2584f521 PG |
179 | - The finalized and tagged releases of all stable kernels can be found |
180 | in separate branches per version at: | |
5fe270a4 | 181 | |
555d4493 | 182 | https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git |
2584f521 | 183 | |
587d39b2 BS |
184 | - The release candidate of all stable kernel versions can be found at: |
185 | ||
186 | https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable-rc.git/ | |
187 | ||
188 | .. warning:: | |
189 | The -stable-rc tree is a snapshot in time of the stable-queue tree and | |
190 | will change frequently, hence will be rebased often. It should only be | |
191 | used for testing purposes (e.g. to be consumed by CI systems). | |
192 | ||
fc185d95 | 193 | |
5fe270a4 MCC |
194 | Review committee |
195 | ---------------- | |
fc185d95 | 196 | |
e48e9909 JJ |
197 | - This is made up of a number of kernel developers who have volunteered for |
198 | this task, and a few that haven't. |