From d0bde9ca0ecff2e58e223dd6ae0e63156553b283 Mon Sep 17 00:00:00 2001 From: Thorsten Leemhuis Date: Tue, 11 Jul 2023 08:19:53 +0200 Subject: docs: stable-kernel-rules: mention other usages for stable tag comments Document how to delay backporting or send a note to the stable team using shell-style inline comments attached to stable tags. CC: Greg KH CC: Sasha Levin CC: Jonathan Corbet Signed-off-by: Thorsten Leemhuis Link: https://lore.kernel.org/r/bf1489b40ff358b7cb4f7d8cc73d5c7c3c143471.1689056247.git.linux@leemhuis.info Signed-off-by: Greg Kroah-Hartman --- Documentation/process/stable-kernel-rules.rst | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) (limited to 'Documentation/process') diff --git a/Documentation/process/stable-kernel-rules.rst b/Documentation/process/stable-kernel-rules.rst index 51df1197d5ab..de0046c0586b 100644 --- a/Documentation/process/stable-kernel-rules.rst +++ b/Documentation/process/stable-kernel-rules.rst @@ -55,9 +55,10 @@ To have the patch automatically included in the stable tree, add the tag Cc: stable@vger.kernel.org -in the sign-off area. Once the patch is merged it will be applied to -the stable tree without anything else needing to be done by the author -or subsystem maintainer. +in the sign-off area. To accompany a note to the stable team, use a shell-style +inline comment (see below for details). Once the patch is merged it will be +applied to the stable tree without anything else needing to be done by the +author or subsystem maintainer. .. _option_2: @@ -139,6 +140,21 @@ The tag has the meaning of: For each "-stable" tree starting with the specified version. +To delay pick up of patches submitted via :ref:`option_1`, use the following +format: + +.. code-block:: none + + Cc: # after 4 weeks in mainline + +For any other requests related to patches submitted via :ref:`option_1`, just +add a note to the stable tag. This for example can be used to point out known +problems: + +.. code-block:: none + + Cc: # see patch description, needs adjustments for >= 6.3 + Following the submission: - The sender will receive an ACK when the patch has been accepted into the -- cgit v1.2.3 From 33568553b3fc0afe99389ac4c6954c8b6c50e948 Mon Sep 17 00:00:00 2001 From: Thorsten Leemhuis Date: Tue, 11 Jul 2023 08:19:54 +0200 Subject: docs: stable-kernel-rules: make rule section more straight forward Tweak some of the rule text to make things more straight forward, with the goal to stick closely to the intend of the old text: * put the "it or equivalent fix must be upstream" rule at the top, as it's one of the most important ones that at the same time often seems to be missed by developers. * "It must fix only one thing" was dropped, as that is almost always a thing that needs to be handled earlier when the change is mainlined. Furthermore, this is already indirectly covered by the "Separate your changes" section in Documentation/process/submitting-patches.rst which the rules already point to. * six other rules are in the end one rule with clarifications; structure the text accordingly to make it a lot easier to follow and understand the intend. * drop the 'In short, something critical' from one of those notes: it contradicts the "real bug that bothers people" aspect somewhat and does not really add anything CC: Greg KH CC: Sasha Levin CC: Jonathan Corbet Signed-off-by: Thorsten Leemhuis Link: https://lore.kernel.org/r/f83e812879caa978a51a1a7cae7c359f29fc093c.1689056247.git.linux@leemhuis.info Signed-off-by: Greg Kroah-Hartman --- Documentation/process/stable-kernel-rules.rst | 38 +++++++++++++-------------- 1 file changed, 18 insertions(+), 20 deletions(-) (limited to 'Documentation/process') diff --git a/Documentation/process/stable-kernel-rules.rst b/Documentation/process/stable-kernel-rules.rst index de0046c0586b..d3f040c2738e 100644 --- a/Documentation/process/stable-kernel-rules.rst +++ b/Documentation/process/stable-kernel-rules.rst @@ -6,31 +6,29 @@ Everything you ever wanted to know about Linux -stable releases Rules on what kind of patches are accepted, and which ones are not, into the "-stable" tree: + - It or an equivalent fix must already exist in Linus' tree (upstream). - It must be obviously correct and tested. - It cannot be bigger than 100 lines, with context. - - It must fix only one thing. - - It must fix a real bug that bothers people (not a, "This could be a - problem..." type thing). - - It must fix a problem that causes a build error (but not for things - marked CONFIG_BROKEN), an oops, a hang, data corruption, a real - security issue, or some "oh, that's not good" issue. In short, something - critical. - - Serious issues as reported by a user of a distribution kernel may also - be considered if they fix a notable performance or interactivity issue. - As these fixes are not as obvious and have a higher risk of a subtle - regression they should only be submitted by a distribution kernel - maintainer and include an addendum linking to a bugzilla entry if it - exists and additional information on the user-visible impact. - - New device IDs and quirks are also accepted. - - No "theoretical race condition" issues, unless an explanation of how the - race can be exploited is also provided. - - It cannot contain any "trivial" fixes in it (spelling changes, - whitespace cleanups, etc). - It must follow the :ref:`Documentation/process/submitting-patches.rst ` rules. - - It or an equivalent fix must already exist in Linus' tree (upstream). - + - It must either fix a real bug that bothers people or just add a device ID. + To elaborate on the former: + + - It fixes a problem like an oops, a hang, data corruption, a real security + issue, a hardware quirk, a build error (but not for things marked + CONFIG_BROKEN), or some "oh, that's not good" issue. + - Serious issues as reported by a user of a distribution kernel may also + be considered if they fix a notable performance or interactivity issue. + As these fixes are not as obvious and have a higher risk of a subtle + regression they should only be submitted by a distribution kernel + maintainer and include an addendum linking to a bugzilla entry if it + exists and additional information on the user-visible impact. + - No "This could be a problem..." type of things like a "theoretical race + condition", unless an explanation of how the bug can be exploited is also + provided. + - No "trivial" fixes without benefit for users (spelling changes, whitespace + cleanups, etc). Procedure for submitting patches to the -stable tree ---------------------------------------------------- -- cgit v1.2.3 From 0f11447d9fcc195a8b3333d21dae69b914e71b94 Mon Sep 17 00:00:00 2001 From: Thorsten Leemhuis Date: Sat, 5 Aug 2023 09:21:29 +0200 Subject: docs: stable-kernel-rules: improve structure by changing headlines * replace a needless sub-heading with a short intro sentence * make "Following the submission" a proper sub-section with a headline without changing the text of the section CC: Greg KH CC: Sasha Levin CC: Jonathan Corbet Signed-off-by: Thorsten Leemhuis Link: https://lore.kernel.org/r/0737676f951050b2ec39e1662ffea37d77ef0bec.1691219455.git.linux@leemhuis.info Signed-off-by: Greg Kroah-Hartman --- Documentation/process/stable-kernel-rules.rst | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) (limited to 'Documentation/process') diff --git a/Documentation/process/stable-kernel-rules.rst b/Documentation/process/stable-kernel-rules.rst index d3f040c2738e..e68a76abe44b 100644 --- a/Documentation/process/stable-kernel-rules.rst +++ b/Documentation/process/stable-kernel-rules.rst @@ -39,8 +39,7 @@ Procedure for submitting patches to the -stable tree process but should follow the procedures in :ref:`Documentation/process/security-bugs.rst `. -For all other submissions, choose one of the following procedures ------------------------------------------------------------------ +There are three options to submit a change to -stable trees: .. _option_1: @@ -153,13 +152,15 @@ problems: Cc: # see patch description, needs adjustments for >= 6.3 -Following the submission: +Following the submission +------------------------ - - The sender will receive an ACK when the patch has been accepted into the - queue, or a NAK if the patch is rejected. This response might take a few - days, according to the developer's schedules. - - If accepted, the patch will be added to the -stable queue, for review by - other developers and by the relevant subsystem maintainer. +The sender will receive an ACK when the patch has been accepted into the +queue, or a NAK if the patch is rejected. This response might take a few +days, according to the developer's schedules. + +If accepted, the patch will be added to the -stable queue, for review by other +developers and by the relevant subsystem maintainer. Review cycle -- cgit v1.2.3 From 3feb21bb0bb41d7785082beaf4686df34c7f074e Mon Sep 17 00:00:00 2001 From: Thorsten Leemhuis Date: Sat, 5 Aug 2023 09:21:30 +0200 Subject: docs: stable-kernel-rules: move text around to improve flow Move the short description about when to use which of the submission options to the top of the section, as it currently sits somewhat odd in the middle between option 3 and examples of option 1. Also move the examples of Option 1 into the section describing it (which in the diff looks like option 2 and 3 are moving down). No text changes, just moving it around. CC: Greg KH CC: Sasha Levin CC: Jonathan Corbet Signed-off-by: Thorsten Leemhuis Link: https://lore.kernel.org/r/16f2377ee40dd7dfa146727fcbe7d1ebccf5b5be.1691219455.git.linux@leemhuis.info Signed-off-by: Greg Kroah-Hartman --- Documentation/process/stable-kernel-rules.rst | 88 +++++++++++++-------------- 1 file changed, 44 insertions(+), 44 deletions(-) (limited to 'Documentation/process') diff --git a/Documentation/process/stable-kernel-rules.rst b/Documentation/process/stable-kernel-rules.rst index e68a76abe44b..61b4701d3469 100644 --- a/Documentation/process/stable-kernel-rules.rst +++ b/Documentation/process/stable-kernel-rules.rst @@ -41,6 +41,13 @@ Procedure for submitting patches to the -stable tree There are three options to submit a change to -stable trees: +:ref:`option_1` is **strongly** preferred, is the easiest and most common. +:ref:`option_2` and :ref:`option_3` are more useful if the patch isn't deemed +worthy at the time it is applied to a public git tree (for instance, because +it deserves more regression testing first). :ref:`option_3` is especially +useful if the original upstream patch needs to be backported (for example +the backport needs some special handling due to e.g. API changes). + .. _option_1: Option 1 @@ -57,50 +64,6 @@ inline comment (see below for details). Once the patch is merged it will be applied to the stable tree without anything else needing to be done by the author or subsystem maintainer. -.. _option_2: - -Option 2 -******** - -After the patch has been merged to Linus' tree, send an email to -stable@vger.kernel.org containing the subject of the patch, the commit ID, -why you think it should be applied, and what kernel version you wish it to -be applied to. - -.. _option_3: - -Option 3 -******** - -Send the patch, after verifying that it follows the above rules, to -stable@vger.kernel.org. You must note the upstream commit ID in the -changelog of your submission, as well as the kernel version you wish -it to be applied to. - -:ref:`option_1` is **strongly** preferred, is the easiest and most common. -:ref:`option_2` and :ref:`option_3` are more useful if the patch isn't deemed -worthy at the time it is applied to a public git tree (for instance, because -it deserves more regression testing first). :ref:`option_3` is especially -useful if the original upstream patch needs to be backported (for example -the backport needs some special handling due to e.g. API changes). - -Note that for :ref:`option_3`, if the patch deviates from the original -upstream patch (for example because it had to be backported) this must be very -clearly documented and justified in the patch description. - -The upstream commit ID must be specified with a separate line above the commit -text, like this: - -.. code-block:: none - - commit upstream. - -or alternatively: - -.. code-block:: none - - [ Upstream commit ] - Additionally, some patches submitted via :ref:`option_1` may have additional patch prerequisites which can be cherry-picked. This can be specified in the following format in the sign-off area: @@ -152,6 +115,43 @@ problems: Cc: # see patch description, needs adjustments for >= 6.3 +.. _option_2: + +Option 2 +******** + +After the patch has been merged to Linus' tree, send an email to +stable@vger.kernel.org containing the subject of the patch, the commit ID, +why you think it should be applied, and what kernel version you wish it to +be applied to. + +.. _option_3: + +Option 3 +******** + +Send the patch, after verifying that it follows the above rules, to +stable@vger.kernel.org. You must note the upstream commit ID in the +changelog of your submission, as well as the kernel version you wish +it to be applied to. + +Note that for :ref:`option_3`, if the patch deviates from the original +upstream patch (for example because it had to be backported) this must be very +clearly documented and justified in the patch description. + +The upstream commit ID must be specified with a separate line above the commit +text, like this: + +.. code-block:: none + + commit upstream. + +or alternatively: + +.. code-block:: none + + [ Upstream commit ] + Following the submission ------------------------ -- cgit v1.2.3 From 189057a1b61b7ee14fe40911eabc0a74da3cdf88 Mon Sep 17 00:00:00 2001 From: Thorsten Leemhuis Date: Sat, 5 Aug 2023 09:21:31 +0200 Subject: docs: stable-kernel-rules: make the examples for option 1 a proper list Separate the description for option 1 and the examples how to use it by making the latter an indented unordered list. No text changes. CC: Greg KH CC: Sasha Levin CC: Jonathan Corbet Signed-off-by: Thorsten Leemhuis Link: https://lore.kernel.org/r/59deaabfabf0629d7cf2a52b196cec19d1f9ec47.1691219455.git.linux@leemhuis.info Signed-off-by: Greg Kroah-Hartman --- Documentation/process/stable-kernel-rules.rst | 48 ++++++++++++++------------- 1 file changed, 25 insertions(+), 23 deletions(-) (limited to 'Documentation/process') diff --git a/Documentation/process/stable-kernel-rules.rst b/Documentation/process/stable-kernel-rules.rst index 61b4701d3469..597016297fb4 100644 --- a/Documentation/process/stable-kernel-rules.rst +++ b/Documentation/process/stable-kernel-rules.rst @@ -59,16 +59,18 @@ To have the patch automatically included in the stable tree, add the tag Cc: stable@vger.kernel.org -in the sign-off area. To accompany a note to the stable team, use a shell-style -inline comment (see below for details). Once the patch is merged it will be -applied to the stable tree without anything else needing to be done by the -author or subsystem maintainer. +in the sign-off area. Once the patch is merged it will be applied to the +stable tree without anything else needing to be done by the author or +subsystem maintainer. -Additionally, some patches submitted via :ref:`option_1` may have additional -patch prerequisites which can be cherry-picked. This can be specified in the -following format in the sign-off area: +To accompany a note to the stable team, use a shell-style inline comment (see +below for details): -.. code-block:: none + * Additionally, some patches submitted via :ref:`option_1` may have additional + patch prerequisites which can be cherry-picked. This can be specified in the + following format in the sign-off area: + + .. code-block:: none Cc: # 3.3.x: a1f84a3: sched: Check for idle Cc: # 3.3.x: 1b9508f: sched: Rate-limit newidle @@ -76,42 +78,42 @@ following format in the sign-off area: Cc: # 3.3.x Signed-off-by: Ingo Molnar -The tag sequence has the meaning of: + The tag sequence has the meaning of: -.. code-block:: none + .. code-block:: none git cherry-pick a1f84a3 git cherry-pick 1b9508f git cherry-pick fd21073 git cherry-pick -Also, some patches may have kernel version prerequisites. This can be -specified in the following format in the sign-off area: + * Also, some patches may have kernel version prerequisites. This can be + specified in the following format in the sign-off area: -.. code-block:: none + .. code-block:: none Cc: # 3.3.x -The tag has the meaning of: + The tag has the meaning of: -.. code-block:: none + .. code-block:: none git cherry-pick -For each "-stable" tree starting with the specified version. + For each "-stable" tree starting with the specified version. -To delay pick up of patches submitted via :ref:`option_1`, use the following -format: + * To delay pick up of patches submitted via :ref:`option_1`, use the following + format: -.. code-block:: none + .. code-block:: none Cc: # after 4 weeks in mainline -For any other requests related to patches submitted via :ref:`option_1`, just -add a note to the stable tag. This for example can be used to point out known -problems: + * For any other requests related to patches submitted via :ref:`option_1`, just + add a note to the stable tag. This for example can be used to point out known + problems: -.. code-block:: none + .. code-block:: none Cc: # see patch description, needs adjustments for >= 6.3 -- cgit v1.2.3 From 6e160d29f6549a1b05c7ba4add49526e50f23335 Mon Sep 17 00:00:00 2001 From: Thorsten Leemhuis Date: Sat, 5 Aug 2023 09:21:32 +0200 Subject: docs: stable-kernel-rules: fine-tune various details * various fine tuning to the text that cleans up rough edges the three previous preparatory patches left behind to keep the diffs simpler * s/Linus' tree/mainline/g, as that's the term more commonly used and known * create a short intro for the three submission options and streamline the explanation when to use which of them * fix a >= vs <= thinko in an example to make it more straight forward * there were two blank lines before some sub-headings and just one before others; use the former style everywhere CC: Greg KH CC: Sasha Levin CC: Jonathan Corbet Signed-off-by: Thorsten Leemhuis Link: https://lore.kernel.org/r/e1960a70acae2c2f18b838aee9f8bf6055fae89b.1691219455.git.linux@leemhuis.info Signed-off-by: Greg Kroah-Hartman --- Documentation/process/stable-kernel-rules.rst | 72 +++++++++++++++------------ 1 file changed, 40 insertions(+), 32 deletions(-) (limited to 'Documentation/process') diff --git a/Documentation/process/stable-kernel-rules.rst b/Documentation/process/stable-kernel-rules.rst index 597016297fb4..2b7f04211d9d 100644 --- a/Documentation/process/stable-kernel-rules.rst +++ b/Documentation/process/stable-kernel-rules.rst @@ -30,6 +30,7 @@ Rules on what kind of patches are accepted, and which ones are not, into the - No "trivial" fixes without benefit for users (spelling changes, whitespace cleanups, etc). + Procedure for submitting patches to the -stable tree ---------------------------------------------------- @@ -41,33 +42,40 @@ Procedure for submitting patches to the -stable tree There are three options to submit a change to -stable trees: -:ref:`option_1` is **strongly** preferred, is the easiest and most common. -:ref:`option_2` and :ref:`option_3` are more useful if the patch isn't deemed -worthy at the time it is applied to a public git tree (for instance, because -it deserves more regression testing first). :ref:`option_3` is especially -useful if the original upstream patch needs to be backported (for example -the backport needs some special handling due to e.g. API changes). + 1. Add a 'stable tag' to the description of a patch you then submit for + mainline inclusion. + 2. Ask the stable team to pick up a patch already mainlined. + 3. Submit a patch to the stable team that is equivalent to a change already + mainlined. + +The sections below describe each of the options in more detail. + +:ref:`option_1` is **strongly** preferred, it is the easiest and most common. +:ref:`option_2` is mainly meant for changes where backporting was not considered +at the time of submission. :ref:`option_3` is an alternative to the two earlier +options for cases where a mainlined patch needs adjustments to apply in older +series (for example due to API changes). .. _option_1: Option 1 ******** -To have the patch automatically included in the stable tree, add the tag +To have a patch you submit for mainline inclusion later automatically picked up +for stable trees, add the tag .. code-block:: none Cc: stable@vger.kernel.org -in the sign-off area. Once the patch is merged it will be applied to the +in the sign-off area. Once the patch is mainlined it will be applied to the stable tree without anything else needing to be done by the author or subsystem maintainer. -To accompany a note to the stable team, use a shell-style inline comment (see -below for details): +To sent additional instructions to the stable team, use a shell-style inline +comment: - * Additionally, some patches submitted via :ref:`option_1` may have additional - patch prerequisites which can be cherry-picked. This can be specified in the + * To specify any additional patch prerequisites for cherry picking use the following format in the sign-off area: .. code-block:: none @@ -87,8 +95,8 @@ below for details): git cherry-pick fd21073 git cherry-pick - * Also, some patches may have kernel version prerequisites. This can be - specified in the following format in the sign-off area: + * For patches that may have kernel version prerequisites specify them using + the following format in the sign-off area: .. code-block:: none @@ -102,27 +110,28 @@ below for details): For each "-stable" tree starting with the specified version. - * To delay pick up of patches submitted via :ref:`option_1`, use the following - format: + Note, such tagging is unnecessary if the stable team can derive the + appropriate versions from Fixes: tags. + + * To delay pick up of patches, use the following format: .. code-block:: none Cc: # after 4 weeks in mainline - * For any other requests related to patches submitted via :ref:`option_1`, just - add a note to the stable tag. This for example can be used to point out known - problems: + * For any other requests, just add a note to the stable tag. This for example + can be used to point out known problems: .. code-block:: none - Cc: # see patch description, needs adjustments for >= 6.3 + Cc: # see patch description, needs adjustments for <= 6.3 .. _option_2: Option 2 ******** -After the patch has been merged to Linus' tree, send an email to +If the patch already has been merged to mainline, send an email to stable@vger.kernel.org containing the subject of the patch, the commit ID, why you think it should be applied, and what kernel version you wish it to be applied to. @@ -133,16 +142,9 @@ Option 3 ******** Send the patch, after verifying that it follows the above rules, to -stable@vger.kernel.org. You must note the upstream commit ID in the -changelog of your submission, as well as the kernel version you wish -it to be applied to. - -Note that for :ref:`option_3`, if the patch deviates from the original -upstream patch (for example because it had to be backported) this must be very -clearly documented and justified in the patch description. - -The upstream commit ID must be specified with a separate line above the commit -text, like this: +stable@vger.kernel.org and mention the kernel version you wish it to be applied +to. When doing so, you must note the upstream commit ID in the changelog of your +submission with a separate line above the commit text, like this: .. code-block:: none @@ -154,12 +156,17 @@ or alternatively: [ Upstream commit ] +If the submitted patch deviates from the original upstream patch (for example +because it had to be adjusted for the older API), this must be very clearly +documented and justified in the patch description. + + Following the submission ------------------------ The sender will receive an ACK when the patch has been accepted into the queue, or a NAK if the patch is rejected. This response might take a few -days, according to the developer's schedules. +days, according to the schedules of the stable team members. If accepted, the patch will be added to the -stable queue, for review by other developers and by the relevant subsystem maintainer. @@ -191,6 +198,7 @@ Review cycle security kernel team, and not go through the normal review cycle. Contact the kernel security team for more details on this procedure. + Trees ----- -- cgit v1.2.3 From bbaee49cce7c815d1bd6d95b6020b5fe33ba561a Mon Sep 17 00:00:00 2001 From: Thorsten Leemhuis Date: Sat, 5 Aug 2023 09:21:33 +0200 Subject: docs: stable-kernel-rules: mention that regressions must be prevented Document that changes intended for a specific stable series have to be in all newer series still maintained, as otherwise users would run into regressions. CC: Greg KH CC: Sasha Levin CC: Jonathan Corbet Signed-off-by: Thorsten Leemhuis Link: https://lore.kernel.org/r/ddb5cb0d6b7aa4ef31642cd9657a0fb53d79cddb.1691219455.git.linux@leemhuis.info Signed-off-by: Greg Kroah-Hartman --- Documentation/process/stable-kernel-rules.rst | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) (limited to 'Documentation/process') diff --git a/Documentation/process/stable-kernel-rules.rst b/Documentation/process/stable-kernel-rules.rst index 2b7f04211d9d..41f1e07abfdf 100644 --- a/Documentation/process/stable-kernel-rules.rst +++ b/Documentation/process/stable-kernel-rules.rst @@ -56,6 +56,12 @@ at the time of submission. :ref:`option_3` is an alternative to the two earlier options for cases where a mainlined patch needs adjustments to apply in older series (for example due to API changes). +When using option 2 or 3 you can ask for your change to be included in specific +stable series. When doing so, ensure the fix or an equivalent is applicable, +submitted, or already present in all newer stable trees still supported. This is +meant to prevent regressions that users might later encounter on updating, if +e.g. a fix merged for 5.19-rc1 would be backported to 5.10.y, but not to 5.15.y. + .. _option_1: Option 1 @@ -133,7 +139,7 @@ Option 2 If the patch already has been merged to mainline, send an email to stable@vger.kernel.org containing the subject of the patch, the commit ID, -why you think it should be applied, and what kernel version you wish it to +why you think it should be applied, and what kernel versions you wish it to be applied to. .. _option_3: @@ -142,7 +148,7 @@ Option 3 ******** Send the patch, after verifying that it follows the above rules, to -stable@vger.kernel.org and mention the kernel version you wish it to be applied +stable@vger.kernel.org and mention the kernel versions you wish it to be applied to. When doing so, you must note the upstream commit ID in the changelog of your submission with a separate line above the commit text, like this: -- cgit v1.2.3