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