1 .. _stable_kernel_rules: 1 .. _stable_kernel_rules:
2 2
3 Everything you ever wanted to know about Linux 3 Everything you ever wanted to know about Linux -stable releases
4 ============================================== 4 ===============================================================
5 5
6 Rules on what kind of patches are accepted, an 6 Rules on what kind of patches are accepted, and which ones are not, into the
7 "-stable" tree: 7 "-stable" tree:
8 8
9 - It or an equivalent fix must already exist i !! 9 - It must be obviously correct and tested.
10 - It must be obviously correct and tested. !! 10 - It cannot be bigger than 100 lines, with context.
11 - It cannot be bigger than 100 lines, with con !! 11 - It must fix only one thing.
12 - It must follow the !! 12 - It must fix a real bug that bothers people (not a, "This could be a
13 :ref:`Documentation/process/submitting-patch !! 13 problem..." type thing).
14 rules. !! 14 - It must fix a problem that causes a build error (but not for things
15 - It must either fix a real bug that bothers p !! 15 marked CONFIG_BROKEN), an oops, a hang, data corruption, a real
16 To elaborate on the former: !! 16 security issue, or some "oh, that's not good" issue. In short, something
17 !! 17 critical.
18 - It fixes a problem like an oops, a hang, d !! 18 - Serious issues as reported by a user of a distribution kernel may also
19 issue, a hardware quirk, a build error (bu !! 19 be considered if they fix a notable performance or interactivity issue.
20 CONFIG_BROKEN), or some "oh, that's not go !! 20 As these fixes are not as obvious and have a higher risk of a subtle
21 - Serious issues as reported by a user of a !! 21 regression they should only be submitted by a distribution kernel
22 be considered if they fix a notable perfor !! 22 maintainer and include an addendum linking to a bugzilla entry if it
23 As these fixes are not as obvious and have !! 23 exists and additional information on the user-visible impact.
24 regression they should only be submitted b !! 24 - New device IDs and quirks are also accepted.
25 maintainer and include an addendum linking !! 25 - No "theoretical race condition" issues, unless an explanation of how the
26 exists and additional information on the u !! 26 race can be exploited is also provided.
27 - No "This could be a problem..." type of th !! 27 - It cannot contain any "trivial" fixes in it (spelling changes,
28 condition", unless an explanation of how t !! 28 whitespace cleanups, etc).
29 provided. !! 29 - It must follow the
30 - No "trivial" fixes without benefit for use !! 30 :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
31 cleanups, etc). !! 31 rules.
>> 32 - It or an equivalent fix must already exist in Linus' tree (upstream).
32 33
33 34
34 Procedure for submitting patches to the -stabl 35 Procedure for submitting patches to the -stable tree
35 ---------------------------------------------- 36 ----------------------------------------------------
36 37
37 .. note:: 38 .. note::
38 39
39 Security patches should not be handled (sol 40 Security patches should not be handled (solely) by the -stable review
40 process but should follow the procedures in 41 process but should follow the procedures in
41 :ref:`Documentation/process/security-bugs.r !! 42 :ref:`Documentation/admin-guide/security-bugs.rst <securitybugs>`.
42 43
43 There are three options to submit a change to !! 44 For all other submissions, choose one of the following procedures
44 !! 45 -----------------------------------------------------------------
45 1. Add a 'stable tag' to the description of a <<
46 mainline inclusion. <<
47 2. Ask the stable team to pick up a patch alre <<
48 3. Submit a patch to the stable team that is e <<
49 mainlined. <<
50 <<
51 The sections below describe each of the option <<
52 <<
53 :ref:`option_1` is **strongly** preferred, it <<
54 :ref:`option_2` is mainly meant for changes wh <<
55 at the time of submission. :ref:`option_3` is <<
56 options for cases where a mainlined patch need <<
57 series (for example due to API changes). <<
58 <<
59 When using option 2 or 3 you can ask for your <<
60 stable series. When doing so, ensure the fix o <<
61 submitted, or already present in all newer sta <<
62 meant to prevent regressions that users might <<
63 e.g. a fix merged for 5.19-rc1 would be backpo <<
64 46
65 .. _option_1: 47 .. _option_1:
66 48
67 Option 1 49 Option 1
68 ******** 50 ********
69 51
70 To have a patch you submit for mainline inclus !! 52 To have the patch automatically included in the stable tree, add the tag
71 for stable trees, add this tag in the sign-off <<
72 <<
73 Cc: stable@vger.kernel.org <<
74 <<
75 Use ``Cc: stable@kernel.org`` instead when fix <<
76 it reduces the chance of accidentally exposing <<
77 'git send-email', as mails sent to that addres <<
78 <<
79 Once the patch is mainlined it will be applied <<
80 anything else needing to be done by the author <<
81 53
82 To send additional instructions to the stable !! 54 .. code-block:: none
83 comment to pass arbitrary or predefined notes: <<
84 55
85 * Specify any additional patch prerequisites f !! 56 Cc: stable@vger.kernel.org
86 57
87 Cc: <stable@vger.kernel.org> # 3.3.x: a1f84 !! 58 in the sign-off area. Once the patch is merged it will be applied to
88 Cc: <stable@vger.kernel.org> # 3.3.x: 1b950 !! 59 the stable tree without anything else needing to be done by the author
89 Cc: <stable@vger.kernel.org> # 3.3.x: fd210 !! 60 or subsystem maintainer.
90 Cc: <stable@vger.kernel.org> # 3.3.x <<
91 Signed-off-by: Ingo Molnar <mingo@elte.hu> <<
92 61
93 The tag sequence has the meaning of:: !! 62 .. _option_2:
94 <<
95 git cherry-pick a1f84a3 <<
96 git cherry-pick 1b9508f <<
97 git cherry-pick fd21073 <<
98 git cherry-pick <this commit> <<
99 <<
100 Note that for a patch series, you do not hav <<
101 patches present in the series itself. For ex <<
102 patch series:: <<
103 63
104 patch1 !! 64 Option 2
105 patch2 !! 65 ********
106 66
107 where patch2 depends on patch1, you do not h !! 67 After the patch has been merged to Linus' tree, send an email to
108 prerequisite of patch2 if you have already m !! 68 stable@vger.kernel.org containing the subject of the patch, the commit ID,
109 inclusion. !! 69 why you think it should be applied, and what kernel version you wish it to
>> 70 be applied to.
110 71
111 * Point out kernel version prerequisites:: !! 72 .. _option_3:
112 73
113 Cc: <stable@vger.kernel.org> # 3.3.x !! 74 Option 3
>> 75 ********
114 76
115 The tag has the meaning of:: !! 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.
116 81
117 git cherry-pick <this commit> !! 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
>> 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).
118 88
119 For each "-stable" tree starting with the sp !! 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.
120 92
121 Note, such tagging is unnecessary if the sta !! 93 The upstream commit ID must be specified with a separate line above the commit
122 appropriate versions from Fixes: tags. !! 94 text, like this:
123 95
124 * Delay pick up of patches:: !! 96 .. code-block:: none
125 97
126 Cc: <stable@vger.kernel.org> # after -rc3 !! 98 commit <sha1> upstream.
127 99
128 * Point out known problems:: !! 100 or alternatively:
129 101
130 Cc: <stable@vger.kernel.org> # see patch de !! 102 .. code-block:: none
131 103
132 There furthermore is a variant of the stable t !! 104 [ Upstream commit <sha1> ]
133 team's backporting tools (e.g AUTOSEL or scrip <<
134 containing a 'Fixes:' tag) ignore a change:: <<
135 105
136 Cc: <stable+noautosel@kernel.org> # reason !! 106 Additionally, some patches submitted via :ref:`option_1` may have additional
>> 107 patch prerequisites which can be cherry-picked. This can be specified in the
>> 108 following format in the sign-off area:
137 109
138 .. _option_2: !! 110 .. code-block:: none
139 111
140 Option 2 !! 112 Cc: <stable@vger.kernel.org> # 3.3.x: a1f84a3: sched: Check for idle
141 ******** !! 113 Cc: <stable@vger.kernel.org> # 3.3.x: 1b9508f: sched: Rate-limit newidle
>> 114 Cc: <stable@vger.kernel.org> # 3.3.x: fd21073: sched: Fix affinity logic
>> 115 Cc: <stable@vger.kernel.org> # 3.3.x
>> 116 Signed-off-by: Ingo Molnar <mingo@elte.hu>
142 117
143 If the patch already has been merged to mainli !! 118 The tag sequence has the meaning of:
144 stable@vger.kernel.org containing the subject <<
145 why you think it should be applied, and what k <<
146 be applied to. <<
147 119
148 .. _option_3: !! 120 .. code-block:: none
149 121
150 Option 3 !! 122 git cherry-pick a1f84a3
151 ******** !! 123 git cherry-pick 1b9508f
>> 124 git cherry-pick fd21073
>> 125 git cherry-pick <this commit>
152 126
153 Send the patch, after verifying that it follow !! 127 Also, some patches may have kernel version prerequisites. This can be
154 stable@vger.kernel.org and mention the kernel !! 128 specified in the following format in the sign-off area:
155 to. When doing so, you must note the upstream <<
156 submission with a separate line above the comm <<
157 129
158 commit <sha1> upstream. !! 130 .. code-block:: none
159 131
160 Or alternatively:: !! 132 Cc: <stable@vger.kernel.org> # 3.3.x
161 133
162 [ Upstream commit <sha1> ] !! 134 The tag has the meaning of:
163 135
164 If the submitted patch deviates from the origi !! 136 .. code-block:: none
165 because it had to be adjusted for the older AP <<
166 documented and justified in the patch descript <<
167 137
>> 138 git cherry-pick <this commit>
168 139
169 Following the submission !! 140 For each "-stable" tree starting with the specified version.
170 ------------------------ <<
171 141
172 The sender will receive an ACK when the patch !! 142 Following the submission:
173 queue, or a NAK if the patch is rejected. Thi <<
174 days, according to the schedules of the stable <<
175 143
176 If accepted, the patch will be added to the -s !! 144 - The sender will receive an ACK when the patch has been accepted into the
177 developers and by the relevant subsystem maint !! 145 queue, or a NAK if the patch is rejected. This response might take a few
>> 146 days, according to the developer's schedules.
>> 147 - If accepted, the patch will be added to the -stable queue, for review by
>> 148 other developers and by the relevant subsystem maintainer.
178 149
179 150
180 Review cycle 151 Review cycle
181 ------------ 152 ------------
182 153
183 - When the -stable maintainers decide for a re !! 154 - When the -stable maintainers decide for a review cycle, the patches will be
184 sent to the review committee, and the mainta !! 155 sent to the review committee, and the maintainer of the affected area of
185 the patch (unless the submitter is the maint !! 156 the patch (unless the submitter is the maintainer of the area) and CC: to
186 the linux-kernel mailing list. !! 157 the linux-kernel mailing list.
187 - The review committee has 48 hours in which t !! 158 - The review committee has 48 hours in which to ACK or NAK the patch.
188 - If the patch is rejected by a member of the !! 159 - If the patch is rejected by a member of the committee, or linux-kernel
189 members object to the patch, bringing up iss !! 160 members object to the patch, bringing up issues that the maintainers and
190 members did not realize, the patch will be d !! 161 members did not realize, the patch will be dropped from the queue.
191 - The ACKed patches will be posted again as pa !! 162 - The ACKed patches will be posted again as part of release candidate (-rc)
192 to be tested by developers and testers. !! 163 to be tested by developers and testers.
193 - Usually only one -rc release is made, howeve !! 164 - Usually only one -rc release is made, however if there are any outstanding
194 issues, some patches may be modified or drop !! 165 issues, some patches may be modified or dropped or additional patches may
195 be queued. Additional -rc releases are then !! 166 be queued. Additional -rc releases are then released and tested until no
196 issues are found. !! 167 issues are found.
197 - Responding to the -rc releases can be done o !! 168 - Responding to the -rc releases can be done on the mailing list by sending
198 a "Tested-by:" email with any testing inform !! 169 a "Tested-by:" email with any testing information desired. The "Tested-by:"
199 tags will be collected and added to the rele !! 170 tags will be collected and added to the release commit.
200 - At the end of the review cycle, the new -sta !! 171 - At the end of the review cycle, the new -stable release will be released
201 containing all the queued and tested patches !! 172 containing all the queued and tested patches.
202 - Security patches will be accepted into the - !! 173 - Security patches will be accepted into the -stable tree directly from the
203 security kernel team, and not go through the !! 174 security kernel team, and not go through the normal review cycle.
204 Contact the kernel security team for more de !! 175 Contact the kernel security team for more details on this procedure.
205 <<
206 176
207 Trees 177 Trees
208 ----- 178 -----
209 179
210 - The queues of patches, for both completed ve !! 180 - The queues of patches, for both completed versions and in progress
211 versions can be found at: !! 181 versions can be found at:
212 182
213 https://git.kernel.org/pub/scm/linux/kerne !! 183 https://git.kernel.org/pub/scm/linux/kernel/git/stable/stable-queue.git
214 184
215 - The finalized and tagged releases of all sta !! 185 - The finalized and tagged releases of all stable kernels can be found
216 in separate branches per version at: !! 186 in separate branches per version at:
217 187
218 https://git.kernel.org/pub/scm/linux/kerne !! 188 https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
219 189
220 - The release candidate of all stable kernel v !! 190 - The release candidate of all stable kernel versions can be found at:
221 191
222 https://git.kernel.org/pub/scm/linux/kerne !! 192 https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable-rc.git/
223 193
224 .. warning:: !! 194 .. warning::
225 The -stable-rc tree is a snapshot in time !! 195 The -stable-rc tree is a snapshot in time of the stable-queue tree and
226 will change frequently, hence will be reb !! 196 will change frequently, hence will be rebased often. It should only be
227 used for testing purposes (e.g. to be con !! 197 used for testing purposes (e.g. to be consumed by CI systems).
228 198
229 199
230 Review committee 200 Review committee
231 ---------------- 201 ----------------
232 202
233 - This is made up of a number of kernel develo !! 203 - This is made up of a number of kernel developers who have volunteered for
234 this task, and a few that haven't. !! 204 this task, and a few that haven't.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.