From nobody Wed Feb 11 05:42:03 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