| 1 | .. _stable_kernel_rules:
|
| 2 |
|
| 3 | Everything you ever wanted to know about Linux -stable releases
|
| 4 | ===============================================================
|
| 5 |
|
| 6 | Rules 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 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).
|
| 32 |
|
| 33 |
|
| 34 | Procedure for submitting patches to the -stable tree
|
| 35 | ----------------------------------------------------
|
| 36 |
|
| 37 | .. note::
|
| 38 |
|
| 39 | Security patches should not be handled (solely) by the -stable review
|
| 40 | process but should follow the procedures in
|
| 41 | :ref:`Documentation/process/security-bugs.rst <securitybugs>`.
|
| 42 |
|
| 43 | There are three options to submit a change to -stable trees:
|
| 44 |
|
| 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.
|
| 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).
|
| 58 |
|
| 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 |
|
| 65 | .. _option_1:
|
| 66 |
|
| 67 | Option 1
|
| 68 | ********
|
| 69 |
|
| 70 | To have a patch you submit for mainline inclusion later automatically picked up
|
| 71 | for stable trees, add this tag in the sign-off area::
|
| 72 |
|
| 73 | Cc: [email protected]
|
| 74 |
|
| 75 | Use ``Cc: [email protected]`` 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 |
|
| 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.
|
| 81 |
|
| 82 | To send additional instructions to the stable team, use a shell-style inline
|
| 83 | comment to pass arbitrary or predefined notes:
|
| 84 |
|
| 85 | * Specify any additional patch prerequisites for cherry picking::
|
| 86 |
|
| 87 | Cc: <[email protected]> # 3.3.x: a1f84a3: sched: Check for idle
|
| 88 | Cc: <[email protected]> # 3.3.x: 1b9508f: sched: Rate-limit newidle
|
| 89 | Cc: <[email protected]> # 3.3.x: fd21073: sched: Fix affinity logic
|
| 90 | Cc: <[email protected]> # 3.3.x
|
| 91 | Signed-off-by: Ingo Molnar <[email protected]>
|
| 92 |
|
| 93 | The tag sequence has the meaning of::
|
| 94 |
|
| 95 | git cherry-pick a1f84a3
|
| 96 | git cherry-pick 1b9508f
|
| 97 | git cherry-pick fd21073
|
| 98 | git cherry-pick <this commit>
|
| 99 |
|
| 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::
|
| 103 |
|
| 104 | patch1
|
| 105 | patch2
|
| 106 |
|
| 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.
|
| 110 |
|
| 111 | * Point out kernel version prerequisites::
|
| 112 |
|
| 113 | Cc: <[email protected]> # 3.3.x
|
| 114 |
|
| 115 | The tag has the meaning of::
|
| 116 |
|
| 117 | git cherry-pick <this commit>
|
| 118 |
|
| 119 | For each "-stable" tree starting with the specified version.
|
| 120 |
|
| 121 | Note, such tagging is unnecessary if the stable team can derive the
|
| 122 | appropriate versions from Fixes: tags.
|
| 123 |
|
| 124 | * Delay pick up of patches::
|
| 125 |
|
| 126 | Cc: <[email protected]> # after -rc3
|
| 127 |
|
| 128 | * Point out known problems::
|
| 129 |
|
| 130 | Cc: <[email protected]> # see patch description, needs adjustments for <= 6.3
|
| 131 |
|
| 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: <[email protected]> # reason goes here, and must be present
|
| 137 |
|
| 138 | .. _option_2:
|
| 139 |
|
| 140 | Option 2
|
| 141 | ********
|
| 142 |
|
| 143 | If the patch already has been merged to mainline, send an email to
|
| 144 | [email protected] containing the subject of the patch, the commit ID,
|
| 145 | why you think it should be applied, and what kernel versions you wish it to
|
| 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
|
| 154 | [email protected] and mention the kernel versions you wish it to be applied
|
| 155 | to. When doing so, you must note the upstream commit ID in the changelog of your
|
| 156 | submission with a separate line above the commit text, like this::
|
| 157 |
|
| 158 | commit <sha1> upstream.
|
| 159 |
|
| 160 | Or alternatively::
|
| 161 |
|
| 162 | [ Upstream commit <sha1> ]
|
| 163 |
|
| 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 |
|
| 169 | Following the submission
|
| 170 | ------------------------
|
| 171 |
|
| 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
|
| 174 | days, according to the schedules of the stable team members.
|
| 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.
|
| 178 |
|
| 179 |
|
| 180 | Review cycle
|
| 181 | ------------
|
| 182 |
|
| 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.
|
| 205 |
|
| 206 |
|
| 207 | Trees
|
| 208 | -----
|
| 209 |
|
| 210 | - The queues of patches, for both completed versions and in progress
|
| 211 | versions can be found at:
|
| 212 |
|
| 213 | https://git.kernel.org/pub/scm/linux/kernel/git/stable/stable-queue.git
|
| 214 |
|
| 215 | - The finalized and tagged releases of all stable kernels can be found
|
| 216 | in separate branches per version at:
|
| 217 |
|
| 218 | https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
|
| 219 |
|
| 220 | - The release candidate of all stable kernel versions can be found at:
|
| 221 |
|
| 222 | https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable-rc.git/
|
| 223 |
|
| 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).
|
| 228 |
|
| 229 |
|
| 230 | Review committee
|
| 231 | ----------------
|
| 232 |
|
| 233 | - This is made up of a number of kernel developers who have volunteered for
|
| 234 | this task, and a few that haven't.
|