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