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 - Security patches should not be handled (solely) by the -stable review
38 <<
39 Security patches should not be handled (sol <<
40 process but should follow the procedures in 39 process but should follow the procedures in
41 :ref:`Documentation/process/security-bugs.r !! 40 :ref:`Documentation/admin-guide/security-bugs.rst <securitybugs>`.
42 <<
43 There are three options to submit a change to <<
44 41
45 1. Add a 'stable tag' to the description of a !! 42 For all other submissions, choose one of the following procedures
46 mainline inclusion. !! 43 -----------------------------------------------------------------
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 44
65 .. _option_1: 45 .. _option_1:
66 46
67 Option 1 47 Option 1
68 ******** 48 ********
69 49
70 To have a patch you submit for mainline inclus !! 50 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 <<
82 To send additional instructions to the stable <<
83 comment to pass arbitrary or predefined notes: <<
84 <<
85 * Specify any additional patch prerequisites f <<
86 <<
87 Cc: <stable@vger.kernel.org> # 3.3.x: a1f84 <<
88 Cc: <stable@vger.kernel.org> # 3.3.x: 1b950 <<
89 Cc: <stable@vger.kernel.org> # 3.3.x: fd210 <<
90 Cc: <stable@vger.kernel.org> # 3.3.x <<
91 Signed-off-by: Ingo Molnar <mingo@elte.hu> <<
92 51
93 The tag sequence has the meaning of:: !! 52 .. code-block:: none
94 53
95 git cherry-pick a1f84a3 !! 54 Cc: stable@vger.kernel.org
96 git cherry-pick 1b9508f <<
97 git cherry-pick fd21073 <<
98 git cherry-pick <this commit> <<
99 55
100 Note that for a patch series, you do not hav !! 56 in the sign-off area. Once the patch is merged it will be applied to
101 patches present in the series itself. For ex !! 57 the stable tree without anything else needing to be done by the author
102 patch series:: !! 58 or subsystem maintainer.
103 59
104 patch1 !! 60 .. _option_2:
105 patch2 <<
106 <<
107 where patch2 depends on patch1, you do not h <<
108 prerequisite of patch2 if you have already m <<
109 inclusion. <<
110 <<
111 * Point out kernel version prerequisites:: <<
112 61
113 Cc: <stable@vger.kernel.org> # 3.3.x !! 62 Option 2
>> 63 ********
114 64
115 The tag has the meaning of:: !! 65 After the patch has been merged to Linus' tree, send an email to
>> 66 stable@vger.kernel.org containing the subject of the patch, the commit ID,
>> 67 why you think it should be applied, and what kernel version you wish it to
>> 68 be applied to.
116 69
117 git cherry-pick <this commit> !! 70 .. _option_3:
118 71
119 For each "-stable" tree starting with the sp !! 72 Option 3
>> 73 ********
120 74
121 Note, such tagging is unnecessary if the sta !! 75 Send the patch, after verifying that it follows the above rules, to
122 appropriate versions from Fixes: tags. !! 76 stable@vger.kernel.org. You must note the upstream commit ID in the
>> 77 changelog of your submission, as well as the kernel version you wish
>> 78 it to be applied to.
123 79
124 * Delay pick up of patches:: !! 80 :ref:`option_1` is **strongly** preferred, is the easiest and most common.
>> 81 :ref:`option_2` and :ref:`option_3` are more useful if the patch isn't deemed
>> 82 worthy at the time it is applied to a public git tree (for instance, because
>> 83 it deserves more regression testing first). :ref:`option_3` is especially
>> 84 useful if the patch needs some special handling to apply to an older kernel
>> 85 (e.g., if API's have changed in the meantime).
125 86
126 Cc: <stable@vger.kernel.org> # after -rc3 !! 87 Note that for :ref:`option_3`, if the patch deviates from the original
>> 88 upstream patch (for example because it had to be backported) this must be very
>> 89 clearly documented and justified in the patch description.
127 90
128 * Point out known problems:: !! 91 The upstream commit ID must be specified with a separate line above the commit
>> 92 text, like this:
129 93
130 Cc: <stable@vger.kernel.org> # see patch de !! 94 .. code-block:: none
131 95
132 There furthermore is a variant of the stable t !! 96 commit <sha1> upstream.
133 team's backporting tools (e.g AUTOSEL or scrip <<
134 containing a 'Fixes:' tag) ignore a change:: <<
135 97
136 Cc: <stable+noautosel@kernel.org> # reason !! 98 Additionally, some patches submitted via :ref:`option_1` may have additional
>> 99 patch prerequisites which can be cherry-picked. This can be specified in the
>> 100 following format in the sign-off area:
137 101
138 .. _option_2: !! 102 .. code-block:: none
139 103
140 Option 2 !! 104 Cc: <stable@vger.kernel.org> # 3.3.x: a1f84a3: sched: Check for idle
141 ******** !! 105 Cc: <stable@vger.kernel.org> # 3.3.x: 1b9508f: sched: Rate-limit newidle
>> 106 Cc: <stable@vger.kernel.org> # 3.3.x: fd21073: sched: Fix affinity logic
>> 107 Cc: <stable@vger.kernel.org> # 3.3.x
>> 108 Signed-off-by: Ingo Molnar <mingo@elte.hu>
142 109
143 If the patch already has been merged to mainli !! 110 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 111
148 .. _option_3: !! 112 .. code-block:: none
149 113
150 Option 3 !! 114 git cherry-pick a1f84a3
151 ******** !! 115 git cherry-pick 1b9508f
>> 116 git cherry-pick fd21073
>> 117 git cherry-pick <this commit>
152 118
153 Send the patch, after verifying that it follow !! 119 Also, some patches may have kernel version prerequisites. This can be
154 stable@vger.kernel.org and mention the kernel !! 120 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 121
158 commit <sha1> upstream. !! 122 .. code-block:: none
159 123
160 Or alternatively:: !! 124 Cc: <stable@vger.kernel.org> # 3.3.x
161 125
162 [ Upstream commit <sha1> ] !! 126 The tag has the meaning of:
163 127
164 If the submitted patch deviates from the origi !! 128 .. code-block:: none
165 because it had to be adjusted for the older AP <<
166 documented and justified in the patch descript <<
167 129
>> 130 git cherry-pick <this commit>
168 131
169 Following the submission !! 132 For each "-stable" tree starting with the specified version.
170 ------------------------ <<
171 133
172 The sender will receive an ACK when the patch !! 134 Following the submission:
173 queue, or a NAK if the patch is rejected. Thi <<
174 days, according to the schedules of the stable <<
175 135
176 If accepted, the patch will be added to the -s !! 136 - The sender will receive an ACK when the patch has been accepted into the
177 developers and by the relevant subsystem maint !! 137 queue, or a NAK if the patch is rejected. This response might take a few
>> 138 days, according to the developer's schedules.
>> 139 - If accepted, the patch will be added to the -stable queue, for review by
>> 140 other developers and by the relevant subsystem maintainer.
178 141
179 142
180 Review cycle 143 Review cycle
181 ------------ 144 ------------
182 145
183 - When the -stable maintainers decide for a re !! 146 - When the -stable maintainers decide for a review cycle, the patches will be
184 sent to the review committee, and the mainta !! 147 sent to the review committee, and the maintainer of the affected area of
185 the patch (unless the submitter is the maint !! 148 the patch (unless the submitter is the maintainer of the area) and CC: to
186 the linux-kernel mailing list. !! 149 the linux-kernel mailing list.
187 - The review committee has 48 hours in which t !! 150 - 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 !! 151 - If the patch is rejected by a member of the committee, or linux-kernel
189 members object to the patch, bringing up iss !! 152 members object to the patch, bringing up issues that the maintainers and
190 members did not realize, the patch will be d !! 153 members did not realize, the patch will be dropped from the queue.
191 - The ACKed patches will be posted again as pa !! 154 - At the end of the review cycle, the ACKed patches will be added to the
192 to be tested by developers and testers. !! 155 latest -stable release, and a new -stable release will happen.
193 - Usually only one -rc release is made, howeve !! 156 - Security patches will be accepted into the -stable tree directly from the
194 issues, some patches may be modified or drop !! 157 security kernel team, and not go through the normal review cycle.
195 be queued. Additional -rc releases are then !! 158 Contact the kernel security team for more details on this procedure.
196 issues are found. <<
197 - Responding to the -rc releases can be done o <<
198 a "Tested-by:" email with any testing inform <<
199 tags will be collected and added to the rele <<
200 - At the end of the review cycle, the new -sta <<
201 containing all the queued and tested patches <<
202 - Security patches will be accepted into the - <<
203 security kernel team, and not go through the <<
204 Contact the kernel security team for more de <<
205 <<
206 159
207 Trees 160 Trees
208 ----- 161 -----
209 162
210 - The queues of patches, for both completed ve !! 163 - The queues of patches, for both completed versions and in progress
211 versions can be found at: !! 164 versions can be found at:
212 165
213 https://git.kernel.org/pub/scm/linux/kerne !! 166 https://git.kernel.org/pub/scm/linux/kernel/git/stable/stable-queue.git
214 167
215 - The finalized and tagged releases of all sta !! 168 - The finalized and tagged releases of all stable kernels can be found
216 in separate branches per version at: !! 169 in separate branches per version at:
217 170
218 https://git.kernel.org/pub/scm/linux/kerne !! 171 https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
219 172
220 - The release candidate of all stable kernel v !! 173 - The release candidate of all stable kernel versions can be found at:
221 174
222 https://git.kernel.org/pub/scm/linux/kerne !! 175 https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable-rc.git/
223 176
224 .. warning:: !! 177 .. warning::
225 The -stable-rc tree is a snapshot in time !! 178 The -stable-rc tree is a snapshot in time of the stable-queue tree and
226 will change frequently, hence will be reb !! 179 will change frequently, hence will be rebased often. It should only be
227 used for testing purposes (e.g. to be con !! 180 used for testing purposes (e.g. to be consumed by CI systems).
228 181
229 182
230 Review committee 183 Review committee
231 ---------------- 184 ----------------
232 185
233 - This is made up of a number of kernel develo !! 186 - This is made up of a number of kernel developers who have volunteered for
234 this task, and a few that haven't. !! 187 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.