[PATCH v1 4/5] docs: stable-kernel-rules: fine-tune various details

[Thorsten Leemhuis]

* 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@xxxxxxxxxxxxxxxxxxx>
CC: Sasha Levin <sashal@xxxxxxxxxx>
CC: Jonathan Corbet <corbet@xxxxxxx>
Signed-off-by: Thorsten Leemhuis <linux@xxxxxxxxxxxxx>
---
 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@xxxxxxxxxxxxxxx
 
-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@xxxxxxxxxxxxxxx> # 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@xxxxxxxxxxxxxxx> # see patch description, needs adjustments for >= 6.3
+     Cc: <stable@xxxxxxxxxxxxxxx> # 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@xxxxxxxxxxxxxxx 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@xxxxxxxxxxxxxxx.  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@xxxxxxxxxxxxxxx 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