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 <<
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 53
93 The tag sequence has the meaning of:: !! 54 .. code-block:: none
94 55
95 git cherry-pick a1f84a3 !! 56 Cc: stable@vger.kernel.org
96 git cherry-pick 1b9508f <<
97 git cherry-pick fd21073 <<
98 git cherry-pick <this commit> <<
99 57
100 Note that for a patch series, you do not hav !! 58 in the sign-off area. Once the patch is merged it will be applied to
101 patches present in the series itself. For ex !! 59 the stable tree without anything else needing to be done by the author
102 patch series:: !! 60 or subsystem maintainer.
103 61
104 patch1 !! 62 .. _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 63
113 Cc: <stable@vger.kernel.org> # 3.3.x !! 64 Option 2
>> 65 ********
114 66
115 The tag has the meaning of:: !! 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.
116 71
117 git cherry-pick <this commit> !! 72 .. _option_3:
118 73
119 For each "-stable" tree starting with the sp !! 74 Option 3
>> 75 ********
120 76
121 Note, such tagging is unnecessary if the sta !! 77 Send the patch, after verifying that it follows the above rules, to
122 appropriate versions from Fixes: tags. !! 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.
123 81
124 * Delay pick up of patches:: !! 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).
125 88
126 Cc: <stable@vger.kernel.org> # after -rc3 !! 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.
127 92
128 * Point out known problems:: !! 93 The upstream commit ID must be specified with a separate line above the commit
>> 94 text, like this:
129 95
130 Cc: <stable@vger.kernel.org> # see patch de !! 96 .. code-block:: none
131 97
132 There furthermore is a variant of the stable t !! 98 commit <sha1> upstream.
133 team's backporting tools (e.g AUTOSEL or scrip <<
134 containing a 'Fixes:' tag) ignore a change:: <<
135 99
136 Cc: <stable+noautosel@kernel.org> # reason !! 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:
137 103
138 .. _option_2: !! 104 .. code-block:: none
139 105
140 Option 2 !! 106 Cc: <stable@vger.kernel.org> # 3.3.x: a1f84a3: sched: Check for idle
141 ******** !! 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
>> 110 Signed-off-by: Ingo Molnar <mingo@elte.hu>
142 111
143 If the patch already has been merged to mainli !! 112 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 113
148 .. _option_3: !! 114 .. code-block:: none
149 115
150 Option 3 !! 116 git cherry-pick a1f84a3
151 ******** !! 117 git cherry-pick 1b9508f
>> 118 git cherry-pick fd21073
>> 119 git cherry-pick <this commit>
152 120
153 Send the patch, after verifying that it follow !! 121 Also, some patches may have kernel version prerequisites. This can be
154 stable@vger.kernel.org and mention the kernel !! 122 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 123
158 commit <sha1> upstream. !! 124 .. code-block:: none
159 125
160 Or alternatively:: !! 126 Cc: <stable@vger.kernel.org> # 3.3.x
161 127
162 [ Upstream commit <sha1> ] !! 128 The tag has the meaning of:
163 129
164 If the submitted patch deviates from the origi !! 130 .. code-block:: none
165 because it had to be adjusted for the older AP <<
166 documented and justified in the patch descript <<
167 131
>> 132 git cherry-pick <this commit>
168 133
169 Following the submission !! 134 For each "-stable" tree starting with the specified version.
170 ------------------------ <<
171 135
172 The sender will receive an ACK when the patch !! 136 Following the submission:
173 queue, or a NAK if the patch is rejected. Thi <<
174 days, according to the schedules of the stable <<
175 137
176 If accepted, the patch will be added to the -s !! 138 - The sender will receive an ACK when the patch has been accepted into the
177 developers and by the relevant subsystem maint !! 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
>> 142 other developers and by the relevant subsystem maintainer.
178 143
179 144
180 Review cycle 145 Review cycle
181 ------------ 146 ------------
182 147
183 - When the -stable maintainers decide for a re !! 148 - When the -stable maintainers decide for a review cycle, the patches will be
184 sent to the review committee, and the mainta !! 149 sent to the review committee, and the maintainer of the affected area of
185 the patch (unless the submitter is the maint !! 150 the patch (unless the submitter is the maintainer of the area) and CC: to
186 the linux-kernel mailing list. !! 151 the linux-kernel mailing list.
187 - The review committee has 48 hours in which t !! 152 - 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 !! 153 - If the patch is rejected by a member of the committee, or linux-kernel
189 members object to the patch, bringing up iss !! 154 members object to the patch, bringing up issues that the maintainers and
190 members did not realize, the patch will be d !! 155 members did not realize, the patch will be dropped from the queue.
191 - The ACKed patches will be posted again as pa !! 156 - The ACKed patches will be posted again as part of release candidate (-rc)
192 to be tested by developers and testers. !! 157 to be tested by developers and testers.
193 - Usually only one -rc release is made, howeve !! 158 - Usually only one -rc release is made, however if there are any outstanding
194 issues, some patches may be modified or drop !! 159 issues, some patches may be modified or dropped or additional patches may
195 be queued. Additional -rc releases are then !! 160 be queued. Additional -rc releases are then released and tested until no
196 issues are found. !! 161 issues are found.
197 - Responding to the -rc releases can be done o !! 162 - Responding to the -rc releases can be done on the mailing list by sending
198 a "Tested-by:" email with any testing inform !! 163 a "Tested-by:" email with any testing information desired. The "Tested-by:"
199 tags will be collected and added to the rele !! 164 tags will be collected and added to the release commit.
200 - At the end of the review cycle, the new -sta !! 165 - At the end of the review cycle, the new -stable release will be released
201 containing all the queued and tested patches !! 166 containing all the queued and tested patches.
202 - Security patches will be accepted into the - !! 167 - Security patches will be accepted into the -stable tree directly from the
203 security kernel team, and not go through the !! 168 security kernel team, and not go through the normal review cycle.
204 Contact the kernel security team for more de !! 169 Contact the kernel security team for more details on this procedure.
205 <<
206 170
207 Trees 171 Trees
208 ----- 172 -----
209 173
210 - The queues of patches, for both completed ve !! 174 - The queues of patches, for both completed versions and in progress
211 versions can be found at: !! 175 versions can be found at:
212 176
213 https://git.kernel.org/pub/scm/linux/kerne !! 177 https://git.kernel.org/pub/scm/linux/kernel/git/stable/stable-queue.git
214 178
215 - The finalized and tagged releases of all sta !! 179 - The finalized and tagged releases of all stable kernels can be found
216 in separate branches per version at: !! 180 in separate branches per version at:
217 181
218 https://git.kernel.org/pub/scm/linux/kerne !! 182 https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
219 183
220 - The release candidate of all stable kernel v !! 184 - The release candidate of all stable kernel versions can be found at:
221 185
222 https://git.kernel.org/pub/scm/linux/kerne !! 186 https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable-rc.git/
223 187
224 .. warning:: !! 188 .. warning::
225 The -stable-rc tree is a snapshot in time !! 189 The -stable-rc tree is a snapshot in time of the stable-queue tree and
226 will change frequently, hence will be reb !! 190 will change frequently, hence will be rebased often. It should only be
227 used for testing purposes (e.g. to be con !! 191 used for testing purposes (e.g. to be consumed by CI systems).
228 192
229 193
230 Review committee 194 Review committee
231 ---------------- 195 ----------------
232 196
233 - This is made up of a number of kernel develo !! 197 - This is made up of a number of kernel developers who have volunteered for
234 this task, and a few that haven't. !! 198 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.