From nobody Wed Feb 11 04:18:04 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 4CA88EB64DA for ; Mon, 10 Jul 2023 17:10:33 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S232300AbjGJRKb (ORCPT ); Mon, 10 Jul 2023 13:10:31 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:34636 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232113AbjGJRKU (ORCPT ); Mon, 10 Jul 2023 13:10:20 -0400 Received: from wp530.webpack.hosteurope.de (wp530.webpack.hosteurope.de [80.237.130.52]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 83417128; Mon, 10 Jul 2023 10:10:19 -0700 (PDT) Received: from ip4d148da6.dynamic.kabel-deutschland.de ([77.20.141.166] helo=truhe.fritz.box); authenticated by wp530.webpack.hosteurope.de running ExIM with esmtpsa (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) id 1qIuOt-0006Iv-FN; Mon, 10 Jul 2023 19:10:15 +0200 From: Thorsten Leemhuis To: Greg KH , stable@vger.kernel.org Cc: linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Sasha Levin , Jonathan Corbet Subject: [RFC PATCH v1 1/3] docs: stable-kernel-rules: mention other usages for stable tag comments Date: Mon, 10 Jul 2023 19:10:11 +0200 Message-Id: X-Mailer: git-send-email 2.40.1 In-Reply-To: References: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-bounce-key: webpack.hosteurope.de;linux@leemhuis.info;1689009019;f91080f1; X-HE-SMSGID: 1qIuOt-0006Iv-FN Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Type: text/plain; charset="utf-8" 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 --- Documentation/process/stable-kernel-rules.rst | 22 ++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/Documentation/process/stable-kernel-rules.rst b/Documentation/= process/stable-kernel-rules.rst index 51df1197d5ab..6e4026dd6882 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 t= ree, add the tag =20 Cc: stable@vger.kernel.org =20 -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. =20 .. _option_2: =20 @@ -139,6 +140,21 @@ The tag has the meaning of: =20 For each "-stable" tree starting with the specified version. =20 +To delay pick up of patches submitted via :ref:`option_1`, use the followi= ng +format: + +.. code-block:: none + + Cc: # after 4 weeks in mainline + +For any other requests related to patches submitted via :ref:`option_1`, j= ust +add a note to the stable tag. This for example can be used to point out kn= own +problems: + +.. code-block:: none + + Cc: # see patch description, needs adjustmen= ts for >=3D 6.3 + Following the submission: =20 - The sender will receive an ACK when the patch has been accepted into the --=20 2.40.1 From nobody Wed Feb 11 04:18:04 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 8483AC00528 for ; Mon, 10 Jul 2023 17:10:23 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S232161AbjGJRKW (ORCPT ); Mon, 10 Jul 2023 13:10:22 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:34624 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229936AbjGJRKT (ORCPT ); Mon, 10 Jul 2023 13:10:19 -0400 Received: from wp530.webpack.hosteurope.de (wp530.webpack.hosteurope.de [80.237.130.52]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id A1881BB; Mon, 10 Jul 2023 10:10:18 -0700 (PDT) Received: from ip4d148da6.dynamic.kabel-deutschland.de ([77.20.141.166] helo=truhe.fritz.box); authenticated by wp530.webpack.hosteurope.de running ExIM with esmtpsa (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) id 1qIuOt-0006Iv-P7; Mon, 10 Jul 2023 19:10:15 +0200 From: Thorsten Leemhuis To: Greg KH , stable@vger.kernel.org Cc: linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Sasha Levin , Jonathan Corbet Subject: [RFC PATCH v1 2/3] docs: stable-kernel-rules: make rule section more straight forward Date: Mon, 10 Jul 2023 19:10:12 +0200 Message-Id: <420fc78dd7f3cd537143ebdb25a51ea58d3f031d.1689008220.git.linux@leemhuis.info> X-Mailer: git-send-email 2.40.1 In-Reply-To: References: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-bounce-key: webpack.hosteurope.de;linux@leemhuis.info;1689009018;df12a5bf; X-HE-SMSGID: 1qIuOt-0006Iv-P7 Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Type: text/plain; charset="utf-8" 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 ustream" 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. CC: Greg KH CC: Sasha Levin CC: Jonathan Corbet Signed-off-by: Thorsten Leemhuis --- Documentation/process/stable-kernel-rules.rst | 39 +++++++++---------- 1 file changed, 19 insertions(+), 20 deletions(-) diff --git a/Documentation/process/stable-kernel-rules.rst b/Documentation/= process/stable-kernel-rules.rst index 6e4026dd6882..85d5d2368034 100644 --- a/Documentation/process/stable-kernel-rules.rst +++ b/Documentation/process/stable-kernel-rules.rst @@ -6,31 +6,30 @@ Everything you ever wanted to know about Linux -stable re= leases Rules on what kind of patches are accepted, and which ones are not, into t= he "-stable" tree: =20 + - 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, somethi= ng - 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 secu= rity + issue, a hardware quirk, a build error (but not for things marked + CONFIG_BROKEN), or some "oh, that's not good" issue. In short, someth= ing + critical. + - Serious issues as reported by a user of a distribution kernel may also + be considered if they fix a notable performance or interactivity issu= e. + 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 ra= ce + condition", unless an explanation of how the bug can be exploited is = also + provided. + - No "trivial" fixes without benefit for users (spelling changes, white= space + cleanups, etc). =20 Procedure for submitting patches to the -stable tree ---------------------------------------------------- --=20 2.40.1 From nobody Wed Feb 11 04:18:04 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 3CBACEB64D9 for ; Mon, 10 Jul 2023 17:10:29 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S232276AbjGJRK2 (ORCPT ); Mon, 10 Jul 2023 13:10:28 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:34632 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229948AbjGJRKU (ORCPT ); Mon, 10 Jul 2023 13:10:20 -0400 Received: from wp530.webpack.hosteurope.de (wp530.webpack.hosteurope.de [80.237.130.52]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id A24E5C0; Mon, 10 Jul 2023 10:10:18 -0700 (PDT) Received: from ip4d148da6.dynamic.kabel-deutschland.de ([77.20.141.166] helo=truhe.fritz.box); authenticated by wp530.webpack.hosteurope.de running ExIM with esmtpsa (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) id 1qIuOu-0006Iv-2k; Mon, 10 Jul 2023 19:10:16 +0200 From: Thorsten Leemhuis To: Greg KH , stable@vger.kernel.org Cc: linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Sasha Levin , Jonathan Corbet Subject: [RFC PATCH v1 3/3] docs: stable-kernel-rules: improve structure to optimize reading flow Date: Mon, 10 Jul 2023 19:10:13 +0200 Message-Id: X-Mailer: git-send-email 2.40.1 In-Reply-To: References: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-bounce-key: webpack.hosteurope.de;linux@leemhuis.info;1689009018;df12a5bf; X-HE-SMSGID: 1qIuOu-0006Iv-2k Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Type: text/plain; charset="utf-8" Optimize the text flow to make things more straight forward to follow: * remove a subheading without real purpose * after outlining the three options add a section that explains them in more detail; move the "Following the submission" text that set in the middle of this to a later place in the document * a few small clarifications along the way CC: Greg KH CC: Sasha Levin CC: Jonathan Corbet Signed-off-by: Thorsten Leemhuis --- Documentation/process/stable-kernel-rules.rst | 156 +++++++++--------- 1 file changed, 81 insertions(+), 75 deletions(-) diff --git a/Documentation/process/stable-kernel-rules.rst b/Documentation/= process/stable-kernel-rules.rst index 85d5d2368034..a9f36912b9dc 100644 --- a/Documentation/process/stable-kernel-rules.rst +++ b/Documentation/process/stable-kernel-rules.rst @@ -40,74 +40,45 @@ Procedure for submitting patches to the -stable tree process but should follow the procedures in :ref:`Documentation/process/security-bugs.rst `. =20 -For all other submissions, choose one of the following procedures ------------------------------------------------------------------ +There are three options to submit a change to -stable trees: =20 -.. _option_1: + 1. Add a 'stable tag' to the description of a patch you want to mainline. + 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 mainlined pa= tch. =20 -Option 1 -******** - -To have the patch automatically included in the stable tree, add the tag - -.. code-block:: none +The sections below describe each of the options in more detail. =20 - 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. - -.. _option_2: - -Option 2 -******** +:ref:`option_1` is **strongly** preferred, it is the easiest and most comm= on. +:ref:`option_2` and :ref:`option_3` are more useful if the patch isn't dee= med +worthy at the time it is submitted for mainline inclusion (for instance, b= ecause +it deserves more regression testing first). :ref:`option_3` is especially +useful if the original upstream patch needs to be adjusted to be included = in +older series (for example the backport needs some special handling due to = e.g. +API changes). =20 -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_1: =20 -.. _option_3: - -Option 3 +Option 1 ******** =20 -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 dee= med -worthy at the time it is applied to a public git tree (for instance, becau= se -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 co= mmit -text, like this: +To have a patch you submit for mainline inclusion automatically picked up = for +the stable tree later, add the tag =20 .. code-block:: none =20 - commit upstream. - -or alternatively: + Cc: stable@vger.kernel.org =20 -.. code-block:: none +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. =20 - [ Upstream commit ] +You can add a note with additional instructions using a shell-style inline +comment: =20 -Additionally, some patches submitted via :ref:`option_1` may have addition= al -patch prerequisites which can be cherry-picked. This can be specified in t= he -following format in the sign-off area: + * To specify any additional patch prerequisites for cherry picking use the + following format in the sign-off area: =20 -.. code-block:: none + .. code-block:: none =20 Cc: # 3.3.x: a1f84a3: sched: Check for idle Cc: # 3.3.x: 1b9508f: sched: Rate-limit newi= dle @@ -115,53 +86,88 @@ following format in the sign-off area: Cc: # 3.3.x Signed-off-by: Ingo Molnar =20 -The tag sequence has the meaning of: + The tag sequence has the meaning of: =20 -.. code-block:: none + .. code-block:: none =20 git cherry-pick a1f84a3 git cherry-pick 1b9508f git cherry-pick fd21073 git cherry-pick =20 -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 usi= ng + the following format in the sign-off area: =20 -.. code-block:: none + .. code-block:: none =20 Cc: # 3.3.x =20 -The tag has the meaning of: + The tag has the meaning of: =20 -.. code-block:: none + .. code-block:: none =20 git cherry-pick =20 -For each "-stable" tree starting with the specified version. + For each "-stable" tree starting with the specified version. =20 -To delay pick up of patches submitted via :ref:`option_1`, use the followi= ng -format: + * To delay pick up of patches, use the following format: =20 -.. code-block:: none + .. code-block:: none =20 Cc: # after 4 weeks in mainline =20 -For any other requests related to patches submitted via :ref:`option_1`, j= ust -add a note to the stable tag. This for example can be used to point out kn= own -problems: + * For any other requests, just add a note to the stable tag. This for exa= mple + can be used to point out known problems: =20 -.. code-block:: none + .. code-block:: none =20 Cc: # see patch description, needs adjustmen= ts for >=3D 6.3 =20 -Following the submission: +.. _option_2: + +Option 2 +******** + +If the patch already 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 and mention the kernel version you wish it to be ap= plied +to. + +When doing so, you must note the upstream commit ID in the changelog of yo= ur +submission with a separate line above the commit text, like this: + +.. code-block:: none + + commit upstream. + +or alternatively: + +.. code-block:: none + + [ Upstream commit ] + +If the patch submitted using this option deviates from the original upstre= am +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 +------------------------ =20 - - 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 f= ew - 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 q= ueue, +or a NAK if the patch is rejected. This response might take a few days, +according to the developer's schedules. =20 +If accepted, the patch will be added to the -stable queue, for review by o= ther +developers and by the relevant subsystem maintainer. =20 Review cycle ------------ --=20 2.40.1