linux-kernel.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
* [PATCH v1 0/5] docs: stable-kernel-rules: improve structure and a few tweaks
@ 2023-08-05  7:21 Thorsten Leemhuis
  2023-08-05  7:21 ` [PATCH v1 1/5] docs: stable-kernel-rules: improve structure by changing headlines Thorsten Leemhuis
                   ` (5 more replies)
  0 siblings, 6 replies; 8+ messages in thread
From: Thorsten Leemhuis @ 2023-08-05  7:21 UTC (permalink / raw)
  To: Greg KH, stable; +Cc: linux-doc, linux-kernel

When adding something to this document earlier I noticed that readers
need to perform some back and forth to fully understand things; I also
noticed a few other aspects that seemed somewhat odd for me with my
background on writing and editing texts.

Find attached a few patches to improve things. The first three are
mainly moving text around to a structure which is somewhat clearer. They
leave quite a few rough edges behind that are fixed in in the last patch
of the series, which changes a few other changes as well; thx to the
prep patches the diff should be relative straight-forward to understand.

These patches are on-top of the following series that currently is in the 
driver-core-testing branch:
https://lore.kernel.org/all/cover.1689056247.git.linux@leemhuis.info/

Ciao, Thorsten

v1:
* new patch-set based on patch 3/3 and other feedback to the following
  patchset[1], but slit off into a seperate set with four distinct
  patches to make it easier to see what is actually changed
  https://lore.kernel.org/linux-doc/d30686781c47c83927e0a41f6a1167a679fa822c.1689008220.git.linux@leemhuis.info/
* append one more patch for something that came up

Thorsten Leemhuis (5):
  docs: stable-kernel-rules: improve structure by changing headlines
  docs: stable-kernel-rules: move text around to improve flow
  docs: stable-kernel-rules: make the examples for option 1 a proper
    list
  docs: stable-kernel-rules: fine-tune various details
  docs: stable-kernel-rules: mention that regressions must be prevented

 Documentation/process/stable-kernel-rules.rst | 165 ++++++++++--------
 1 file changed, 91 insertions(+), 74 deletions(-)


base-commit: 016571b6d52deb473676fb4d24baf8ed3667ae21
prerequisite-patch-id: b00970f680f3032fe8a7d0e3843b76d60c2f0458
prerequisite-patch-id: 9926a13726e99d51800f52cb84e26ae971757467
-- 
2.40.1


^ permalink raw reply	[flat|nested] 8+ messages in thread

* [PATCH v1 1/5] docs: stable-kernel-rules: improve structure by changing headlines
  2023-08-05  7:21 [PATCH v1 0/5] docs: stable-kernel-rules: improve structure and a few tweaks Thorsten Leemhuis
@ 2023-08-05  7:21 ` Thorsten Leemhuis
  2023-08-05  7:21 ` [PATCH v1 2/5] docs: stable-kernel-rules: move text around to improve flow Thorsten Leemhuis
                   ` (4 subsequent siblings)
  5 siblings, 0 replies; 8+ messages in thread
From: Thorsten Leemhuis @ 2023-08-05  7:21 UTC (permalink / raw)
  To: Greg KH, stable; +Cc: linux-doc, linux-kernel, Sasha Levin, Jonathan Corbet

* 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 <gregkh@linuxfoundation.org>
CC: Sasha Levin <sashal@kernel.org>
CC: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
 Documentation/process/stable-kernel-rules.rst | 17 +++++++++--------
 1 file changed, 9 insertions(+), 8 deletions(-)

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 <securitybugs>`.
 
-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: <stable@vger.kernel.org> # 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
-- 
2.40.1


^ permalink raw reply related	[flat|nested] 8+ messages in thread

* [PATCH v1 2/5] docs: stable-kernel-rules: move text around to improve flow
  2023-08-05  7:21 [PATCH v1 0/5] docs: stable-kernel-rules: improve structure and a few tweaks Thorsten Leemhuis
  2023-08-05  7:21 ` [PATCH v1 1/5] docs: stable-kernel-rules: improve structure by changing headlines Thorsten Leemhuis
@ 2023-08-05  7:21 ` Thorsten Leemhuis
  2023-08-05  7:21 ` [PATCH v1 3/5] docs: stable-kernel-rules: make the examples for option 1 a proper list Thorsten Leemhuis
                   ` (3 subsequent siblings)
  5 siblings, 0 replies; 8+ messages in thread
From: Thorsten Leemhuis @ 2023-08-05  7:21 UTC (permalink / raw)
  To: Greg KH, stable; +Cc: linux-doc, linux-kernel, Sasha Levin, Jonathan Corbet

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 <gregkh@linuxfoundation.org>
CC: Sasha Levin <sashal@kernel.org>
CC: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
 Documentation/process/stable-kernel-rules.rst | 88 +++++++++----------
 1 file changed, 44 insertions(+), 44 deletions(-)

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 <sha1> upstream.
-
-or alternatively:
-
-.. code-block:: none
-
-    [ Upstream commit <sha1> ]
-
 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: <stable@vger.kernel.org> # 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 <sha1> upstream.
+
+or alternatively:
+
+.. code-block:: none
+
+    [ Upstream commit <sha1> ]
+
 Following the submission
 ------------------------
 
-- 
2.40.1


^ permalink raw reply related	[flat|nested] 8+ messages in thread

* [PATCH v1 3/5] docs: stable-kernel-rules: make the examples for option 1 a proper list
  2023-08-05  7:21 [PATCH v1 0/5] docs: stable-kernel-rules: improve structure and a few tweaks Thorsten Leemhuis
  2023-08-05  7:21 ` [PATCH v1 1/5] docs: stable-kernel-rules: improve structure by changing headlines Thorsten Leemhuis
  2023-08-05  7:21 ` [PATCH v1 2/5] docs: stable-kernel-rules: move text around to improve flow Thorsten Leemhuis
@ 2023-08-05  7:21 ` Thorsten Leemhuis
  2023-08-05  7:21 ` [PATCH v1 4/5] docs: stable-kernel-rules: fine-tune various details Thorsten Leemhuis
                   ` (2 subsequent siblings)
  5 siblings, 0 replies; 8+ messages in thread
From: Thorsten Leemhuis @ 2023-08-05  7:21 UTC (permalink / raw)
  To: Greg KH, stable; +Cc: linux-doc, linux-kernel, Sasha Levin, Jonathan Corbet

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 <gregkh@linuxfoundation.org>
CC: Sasha Levin <sashal@kernel.org>
CC: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
 Documentation/process/stable-kernel-rules.rst | 48 ++++++++++---------
 1 file changed, 25 insertions(+), 23 deletions(-)

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: <stable@vger.kernel.org> # 3.3.x: a1f84a3: sched: Check for idle
      Cc: <stable@vger.kernel.org> # 3.3.x: 1b9508f: sched: Rate-limit newidle
@@ -76,42 +78,42 @@ following format in the sign-off area:
      Cc: <stable@vger.kernel.org> # 3.3.x
      Signed-off-by: Ingo Molnar <mingo@elte.hu>
 
-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 <this commit>
 
-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: <stable@vger.kernel.org> # 3.3.x
 
-The tag has the meaning of:
+   The tag has the meaning of:
 
-.. code-block:: none
+   .. code-block:: none
 
      git cherry-pick <this commit>
 
-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: <stable@vger.kernel.org> # 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: <stable@vger.kernel.org> # see patch description, needs adjustments for >= 6.3
 
-- 
2.40.1


^ permalink raw reply related	[flat|nested] 8+ messages in thread

* [PATCH v1 4/5] docs: stable-kernel-rules: fine-tune various details
  2023-08-05  7:21 [PATCH v1 0/5] docs: stable-kernel-rules: improve structure and a few tweaks Thorsten Leemhuis
                   ` (2 preceding siblings ...)
  2023-08-05  7:21 ` [PATCH v1 3/5] docs: stable-kernel-rules: make the examples for option 1 a proper list Thorsten Leemhuis
@ 2023-08-05  7:21 ` Thorsten Leemhuis
  2023-08-05  7:21 ` [PATCH v1 5/5] docs: stable-kernel-rules: mention that regressions must be prevented Thorsten Leemhuis
  2023-08-05  7:54 ` [PATCH v1 0/5] docs: stable-kernel-rules: improve structure and a few tweaks Thorsten Leemhuis
  5 siblings, 0 replies; 8+ messages in thread
From: Thorsten Leemhuis @ 2023-08-05  7:21 UTC (permalink / raw)
  To: Greg KH, stable; +Cc: linux-doc, linux-kernel, Sasha Levin, Jonathan Corbet

* 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 <gregkh@linuxfoundation.org>
CC: Sasha Levin <sashal@kernel.org>
CC: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
 Documentation/process/stable-kernel-rules.rst | 72 ++++++++++---------
 1 file changed, 40 insertions(+), 32 deletions(-)

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 <this commit>
 
- * 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: <stable@vger.kernel.org> # 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: <stable@vger.kernel.org> # see patch description, needs adjustments for >= 6.3
+     Cc: <stable@vger.kernel.org> # 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 <sha1> ]
 
+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
 -----
 
-- 
2.40.1


^ permalink raw reply related	[flat|nested] 8+ messages in thread

* [PATCH v1 5/5] docs: stable-kernel-rules: mention that regressions must be prevented
  2023-08-05  7:21 [PATCH v1 0/5] docs: stable-kernel-rules: improve structure and a few tweaks Thorsten Leemhuis
                   ` (3 preceding siblings ...)
  2023-08-05  7:21 ` [PATCH v1 4/5] docs: stable-kernel-rules: fine-tune various details Thorsten Leemhuis
@ 2023-08-05  7:21 ` Thorsten Leemhuis
  2023-08-05  7:54 ` [PATCH v1 0/5] docs: stable-kernel-rules: improve structure and a few tweaks Thorsten Leemhuis
  5 siblings, 0 replies; 8+ messages in thread
From: Thorsten Leemhuis @ 2023-08-05  7:21 UTC (permalink / raw)
  To: Greg KH, stable; +Cc: linux-doc, linux-kernel, Sasha Levin, Jonathan Corbet

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 <gregkh@linuxfoundation.org>
CC: Sasha Levin <sashal@kernel.org>
CC: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
 Documentation/process/stable-kernel-rules.rst | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

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:
 
-- 
2.40.1


^ permalink raw reply related	[flat|nested] 8+ messages in thread

* Re: [PATCH v1 0/5] docs: stable-kernel-rules: improve structure and a few tweaks
  2023-08-05  7:21 [PATCH v1 0/5] docs: stable-kernel-rules: improve structure and a few tweaks Thorsten Leemhuis
                   ` (4 preceding siblings ...)
  2023-08-05  7:21 ` [PATCH v1 5/5] docs: stable-kernel-rules: mention that regressions must be prevented Thorsten Leemhuis
@ 2023-08-05  7:54 ` Thorsten Leemhuis
  2023-08-12 11:03   ` Greg KH
  5 siblings, 1 reply; 8+ messages in thread
From: Thorsten Leemhuis @ 2023-08-05  7:54 UTC (permalink / raw)
  To: Greg KH, stable; +Cc: linux-doc, linux-kernel, Sasha Levin, Jonathan Corbet

[adding Sasha and Jon to the CC, seem I forget to do that on the cover
letter; sorry!]

On 05.08.23 09:21, Thorsten Leemhuis wrote:
> When adding something to this document earlier I noticed that readers
> need to perform some back and forth to fully understand things; I also
> noticed a few other aspects that seemed somewhat odd for me with my
> background on writing and editing texts.
> 
> Find attached a few patches to improve things. The first three are
> mainly moving text around to a structure which is somewhat clearer. They
> leave quite a few rough edges behind that are fixed in in the last patch
> of the series, which changes a few other changes as well; thx to the
> prep patches the diff should be relative straight-forward to understand.
> 
> These patches are on-top of the following series that currently is in the 
> driver-core-testing branch:
> https://lore.kernel.org/all/cover.1689056247.git.linux@leemhuis.info/

FWIW, in case anyone wonders how the text looks in the end, see:

https://www.leemhuis.info/files/kernel/stable-rules/stable-kernel-rules.txt

https://www.leemhuis.info/files/kernel/stable-rules/Everything%20you%20ever%20wanted%20to%20know%20about%20Linux%20-stable%20releases%20%e2%80%94%20The%20Linux%20Kernel%20documentation.html

Ciao, Thorsten

> v1:
> * new patch-set based on patch 3/3 and other feedback to the following
>   patchset[1], but slit off into a seperate set with four distinct
>   patches to make it easier to see what is actually changed
>   https://lore.kernel.org/linux-doc/d30686781c47c83927e0a41f6a1167a679fa822c.1689008220.git.linux@leemhuis.info/
> * append one more patch for something that came up
> 
> Thorsten Leemhuis (5):
>   docs: stable-kernel-rules: improve structure by changing headlines
>   docs: stable-kernel-rules: move text around to improve flow
>   docs: stable-kernel-rules: make the examples for option 1 a proper
>     list
>   docs: stable-kernel-rules: fine-tune various details
>   docs: stable-kernel-rules: mention that regressions must be prevented
> 
>  Documentation/process/stable-kernel-rules.rst | 165 ++++++++++--------
>  1 file changed, 91 insertions(+), 74 deletions(-)
> 
> 
> base-commit: 016571b6d52deb473676fb4d24baf8ed3667ae21
> prerequisite-patch-id: b00970f680f3032fe8a7d0e3843b76d60c2f0458
> prerequisite-patch-id: 9926a13726e99d51800f52cb84e26ae971757467

^ permalink raw reply	[flat|nested] 8+ messages in thread

* Re: [PATCH v1 0/5] docs: stable-kernel-rules: improve structure and a few tweaks
  2023-08-05  7:54 ` [PATCH v1 0/5] docs: stable-kernel-rules: improve structure and a few tweaks Thorsten Leemhuis
@ 2023-08-12 11:03   ` Greg KH
  0 siblings, 0 replies; 8+ messages in thread
From: Greg KH @ 2023-08-12 11:03 UTC (permalink / raw)
  To: Thorsten Leemhuis
  Cc: stable, linux-doc, linux-kernel, Sasha Levin, Jonathan Corbet

On Sat, Aug 05, 2023 at 09:54:25AM +0200, Thorsten Leemhuis wrote:
> [adding Sasha and Jon to the CC, seem I forget to do that on the cover
> letter; sorry!]
> 
> On 05.08.23 09:21, Thorsten Leemhuis wrote:
> > When adding something to this document earlier I noticed that readers
> > need to perform some back and forth to fully understand things; I also
> > noticed a few other aspects that seemed somewhat odd for me with my
> > background on writing and editing texts.
> > 
> > Find attached a few patches to improve things. The first three are
> > mainly moving text around to a structure which is somewhat clearer. They
> > leave quite a few rough edges behind that are fixed in in the last patch
> > of the series, which changes a few other changes as well; thx to the
> > prep patches the diff should be relative straight-forward to understand.
> > 
> > These patches are on-top of the following series that currently is in the 
> > driver-core-testing branch:
> > https://lore.kernel.org/all/cover.1689056247.git.linux@leemhuis.info/
> 
> FWIW, in case anyone wonders how the text looks in the end, see:
> 
> https://www.leemhuis.info/files/kernel/stable-rules/stable-kernel-rules.txt
> 
> https://www.leemhuis.info/files/kernel/stable-rules/Everything%20you%20ever%20wanted%20to%20know%20about%20Linux%20-stable%20releases%20%e2%80%94%20The%20Linux%20Kernel%20documentation.html

Looks very good, thanks!

greg k-h

^ permalink raw reply	[flat|nested] 8+ messages in thread

end of thread, other threads:[~2023-08-12 11:04 UTC | newest]

Thread overview: 8+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2023-08-05  7:21 [PATCH v1 0/5] docs: stable-kernel-rules: improve structure and a few tweaks Thorsten Leemhuis
2023-08-05  7:21 ` [PATCH v1 1/5] docs: stable-kernel-rules: improve structure by changing headlines Thorsten Leemhuis
2023-08-05  7:21 ` [PATCH v1 2/5] docs: stable-kernel-rules: move text around to improve flow Thorsten Leemhuis
2023-08-05  7:21 ` [PATCH v1 3/5] docs: stable-kernel-rules: make the examples for option 1 a proper list Thorsten Leemhuis
2023-08-05  7:21 ` [PATCH v1 4/5] docs: stable-kernel-rules: fine-tune various details Thorsten Leemhuis
2023-08-05  7:21 ` [PATCH v1 5/5] docs: stable-kernel-rules: mention that regressions must be prevented Thorsten Leemhuis
2023-08-05  7:54 ` [PATCH v1 0/5] docs: stable-kernel-rules: improve structure and a few tweaks Thorsten Leemhuis
2023-08-12 11:03   ` Greg KH

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).