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