1.. _stable_kernel_rules: 2 3Everything you ever wanted to know about Linux -stable releases 4=============================================================== 5 6Rules on what kind of patches are accepted, and which ones are not, into the 7"-stable" tree: 8 9 - It or an equivalent fix must already exist in Linus' tree (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). 32 33Procedure for submitting patches to the -stable tree 34---------------------------------------------------- 35 36.. note:: 37 38 Security patches should not be handled (solely) by the -stable review 39 process but should follow the procedures in 40 :ref:`Documentation/process/security-bugs.rst <securitybugs>`. 41 42There are three options to submit a change to -stable trees: 43 44:ref:`option_1` is **strongly** preferred, is the easiest and most common. 45:ref:`option_2` and :ref:`option_3` are more useful if the patch isn't deemed 46worthy at the time it is applied to a public git tree (for instance, because 47it deserves more regression testing first). :ref:`option_3` is especially 48useful if the original upstream patch needs to be backported (for example 49the backport needs some special handling due to e.g. API changes). 50 51.. _option_1: 52 53Option 1 54******** 55 56To have the patch automatically included in the stable tree, add the tag 57 58.. code-block:: none 59 60 Cc: [email protected] 61 62in the sign-off area. To accompany a note to the stable team, use a shell-style 63inline comment (see below for details). Once the patch is merged it will be 64applied to the stable tree without anything else needing to be done by the 65author or subsystem maintainer. 66 67Additionally, some patches submitted via :ref:`option_1` may have additional 68patch prerequisites which can be cherry-picked. This can be specified in the 69following format in the sign-off area: 70 71.. code-block:: none 72 73 Cc: <[email protected]> # 3.3.x: a1f84a3: sched: Check for idle 74 Cc: <[email protected]> # 3.3.x: 1b9508f: sched: Rate-limit newidle 75 Cc: <[email protected]> # 3.3.x: fd21073: sched: Fix affinity logic 76 Cc: <[email protected]> # 3.3.x 77 Signed-off-by: Ingo Molnar <[email protected]> 78 79The tag sequence has the meaning of: 80 81.. code-block:: none 82 83 git cherry-pick a1f84a3 84 git cherry-pick 1b9508f 85 git cherry-pick fd21073 86 git cherry-pick <this commit> 87 88Also, some patches may have kernel version prerequisites. This can be 89specified in the following format in the sign-off area: 90 91.. code-block:: none 92 93 Cc: <[email protected]> # 3.3.x 94 95The tag has the meaning of: 96 97.. code-block:: none 98 99 git cherry-pick <this commit> 100 101For each "-stable" tree starting with the specified version. 102 103To delay pick up of patches submitted via :ref:`option_1`, use the following 104format: 105 106.. code-block:: none 107 108 Cc: <[email protected]> # after 4 weeks in mainline 109 110For any other requests related to patches submitted via :ref:`option_1`, just 111add a note to the stable tag. This for example can be used to point out known 112problems: 113 114.. code-block:: none 115 116 Cc: <[email protected]> # see patch description, needs adjustments for >= 6.3 117 118.. _option_2: 119 120Option 2 121******** 122 123After the patch has been merged to Linus' tree, send an email to 124[email protected] containing the subject of the patch, the commit ID, 125why you think it should be applied, and what kernel version you wish it to 126be applied to. 127 128.. _option_3: 129 130Option 3 131******** 132 133Send the patch, after verifying that it follows the above rules, to 134[email protected]. You must note the upstream commit ID in the 135changelog of your submission, as well as the kernel version you wish 136it to be applied to. 137 138Note that for :ref:`option_3`, if the patch deviates from the original 139upstream patch (for example because it had to be backported) this must be very 140clearly documented and justified in the patch description. 141 142The upstream commit ID must be specified with a separate line above the commit 143text, like this: 144 145.. code-block:: none 146 147 commit <sha1> upstream. 148 149or alternatively: 150 151.. code-block:: none 152 153 [ Upstream commit <sha1> ] 154 155Following the submission 156------------------------ 157 158The sender will receive an ACK when the patch has been accepted into the 159queue, or a NAK if the patch is rejected. This response might take a few 160days, according to the developer's schedules. 161 162If accepted, the patch will be added to the -stable queue, for review by other 163developers and by the relevant subsystem maintainer. 164 165 166Review cycle 167------------ 168 169 - When the -stable maintainers decide for a review cycle, the patches will be 170 sent to the review committee, and the maintainer of the affected area of 171 the patch (unless the submitter is the maintainer of the area) and CC: to 172 the linux-kernel mailing list. 173 - The review committee has 48 hours in which to ACK or NAK the patch. 174 - If the patch is rejected by a member of the committee, or linux-kernel 175 members object to the patch, bringing up issues that the maintainers and 176 members did not realize, the patch will be dropped from the queue. 177 - The ACKed patches will be posted again as part of release candidate (-rc) 178 to be tested by developers and testers. 179 - Usually only one -rc release is made, however if there are any outstanding 180 issues, some patches may be modified or dropped or additional patches may 181 be queued. Additional -rc releases are then released and tested until no 182 issues are found. 183 - Responding to the -rc releases can be done on the mailing list by sending 184 a "Tested-by:" email with any testing information desired. The "Tested-by:" 185 tags will be collected and added to the release commit. 186 - At the end of the review cycle, the new -stable release will be released 187 containing all the queued and tested patches. 188 - Security patches will be accepted into the -stable tree directly from the 189 security kernel team, and not go through the normal review cycle. 190 Contact the kernel security team for more details on this procedure. 191 192Trees 193----- 194 195 - The queues of patches, for both completed versions and in progress 196 versions can be found at: 197 198 https://git.kernel.org/pub/scm/linux/kernel/git/stable/stable-queue.git 199 200 - The finalized and tagged releases of all stable kernels can be found 201 in separate branches per version at: 202 203 https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git 204 205 - The release candidate of all stable kernel versions can be found at: 206 207 https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable-rc.git/ 208 209 .. warning:: 210 The -stable-rc tree is a snapshot in time of the stable-queue tree and 211 will change frequently, hence will be rebased often. It should only be 212 used for testing purposes (e.g. to be consumed by CI systems). 213 214 215Review committee 216---------------- 217 218 - This is made up of a number of kernel developers who have volunteered for 219 this task, and a few that haven't. 220