lkml.org 
[lkml]   [2016]   [Sep]   [14]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
Patch in this message
/
From
Subject[PATCH v3 15/21] Documentation/stable_kernel_rules.txt: convert it to ReST markup
Date
- 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@s-opensource.com>
---
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@vger.kernel.org
- 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@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_2:

- --- Option 3 ---
+Option 2
+********

- 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.
+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 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@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 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@vger.kernel.org> # 3.3.x: a1f84a3: sched: Check for idle
Cc: <stable@vger.kernel.org> # 3.3.x: 1b9508f: sched: Rate-limit newidle
Cc: <stable@vger.kernel.org> # 3.3.x: fd21073: sched: Fix affinity logic
Cc: <stable@vger.kernel.org> # 3.3.x
- Signed-off-by: Ingo Molnar <mingo@elte.hu>
+ Signed-off-by: Ingo Molnar <mingo@elte.hu>
+
+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@vger.kernel.org> # 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

\
 
 \ /
  Last update: 2016-09-17 09:59    [W:0.193 / U:0.200 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site