- use ReST markups for section headers;
- add cross-references to the options;
- mark code blocks;
- a few minor changes to make Sphinx happy.
Signed-off-by: Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>
---
Documentation/stable_kernel_rules.txt | 101 +++++++++++++++++++++++-----------
1 file changed, 68 insertions(+), 33 deletions(-)
diff --git a/Documentation/stable_kernel_rules.txt b/Documentation/stable_kernel_rules.txt
index ffd4575ec9f2..387d8a44eda2 100644
--- a/Documentation/stable_kernel_rules.txt
+++ b/Documentation/stable_kernel_rules.txt
@@ -1,4 +1,5 @@
-Everything you ever wanted to know about Linux -stable releases.
+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:
@@ -27,7 +28,8 @@ Rules on what kind of patches are accepted, and which ones are not, into the
- It or an equivalent fix must already exist in Linus' tree (upstream).
-Procedure for submitting patches to the -stable tree:
+Procedure for submitting patches to the -stable tree
+----------------------------------------------------
- If the patch covers files in net/ or drivers/net please follow netdev stable
submission guidelines as described in
@@ -35,56 +37,78 @@ Procedure for submitting patches to the -stable tree:
- Security patches should not be handled (solely) by the -stable review
process but should follow the procedures in Documentation/SecurityBugs.
-For all other submissions, choose one of the following procedures:
+For all other submissions, choose one of the following procedures
+-----------------------------------------------------------------
- --- Option 1 ---
+.. _option_1:
+
+Option 1
+********
+
+To have the patch automatically included in the stable tree, add the tag
+
+.. code-block:: none
- To have the patch automatically included in the stable tree, add the tag
Cc: stable@xxxxxxxxxxxxxxx
- 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.
- --- Option 2 ---
+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.
- After the patch has been merged to Linus' tree, 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.
+.. _option_2:
- --- Option 3 ---
+Option 2
+********
- 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.
+After the patch has been merged to Linus' tree, 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.
-Option 1 is *strongly* preferred, is the easiest and most common. Options 2 and
-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). Option 3 is especially useful if the patch needs some special handling
-to apply to an older kernel (e.g., if API's have changed in the meantime).
+.. _option_3:
-Note that for 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.
+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.
+
+: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 patch needs some special handling to apply to an older kernel
+(e.g., if API's have changed in the meantime).
+
+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.
Additionally, some patches submitted via 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@xxxxxxxxxxxxxxx> # 3.3.x: a1f84a3: sched: Check for idle
Cc: <stable@xxxxxxxxxxxxxxx> # 3.3.x: 1b9508f: sched: Rate-limit newidle
Cc: <stable@xxxxxxxxxxxxxxx> # 3.3.x: fd21073: sched: Fix affinity logic
Cc: <stable@xxxxxxxxxxxxxxx> # 3.3.x
- Signed-off-by: Ingo Molnar <mingo@xxxxxxx>
+ Signed-off-by: Ingo Molnar <mingo@xxxxxxx>
+
+The tag sequence has the meaning of:
+
+.. code-block:: none
- The tag sequence has the meaning of:
git cherry-pick a1f84a3
git cherry-pick 1b9508f
git cherry-pick fd21073
@@ -93,12 +117,17 @@ 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
+
Cc: <stable@xxxxxxxxxxxxxxx> # 3.3.x-
- The tag has the meaning of:
+The tag has the meaning of:
+
+.. 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.
Following the submission:
@@ -109,7 +138,8 @@ Following the submission:
other developers and by the relevant subsystem maintainer.
-Review cycle:
+Review cycle
+------------
- When the -stable maintainers decide for a review cycle, the patches will be
sent to the review committee, and the maintainer of the affected area of
@@ -125,17 +155,22 @@ 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:
+Trees
+-----
- The queues of patches, for both completed versions and in progress
versions can be found at:
+
http://git.kernel.org/?p=linux/kernel/git/stable/stable-queue.git
+
- The finalized and tagged releases of all stable kernels can be found
in separate branches per version at:
+
http://git.kernel.org/?p=linux/kernel/git/stable/linux-stable.git
-Review committee:
+Review committee
+----------------
- This is made up of a number of kernel developers who have volunteered for
this task, and a few that haven't.
--
2.7.4
--
To unsubscribe from this list: send the line "unsubscribe stable" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html