From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S932978AbcINLNo (ORCPT ); Wed, 14 Sep 2016 07:13:44 -0400 Received: from bombadil.infradead.org ([198.137.202.9]:40282 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1761639AbcINLM6 (ORCPT ); Wed, 14 Sep 2016 07:12:58 -0400 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab , Markus Heiser , Jonathan Corbet , Jani Nikula , LKML , Greg Kroah-Hartman , stable@vger.kernel.org Subject: [PATCH v3 15/21] Documentation/stable_kernel_rules.txt: convert it to ReST markup Date: Wed, 14 Sep 2016 08:06:44 -0300 Message-Id: <0e542b769856ccc628f4f6c277278f0c91e9dcaf.1473849886.git.mchehab@s-opensource.com> X-Mailer: git-send-email 2.7.4 In-Reply-To: References: In-Reply-To: References: Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org - 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 --- 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 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: # 3.3.x: a1f84a3: sched: Check for idle Cc: # 3.3.x: 1b9508f: sched: Rate-limit newidle Cc: # 3.3.x: fd21073: sched: Fix affinity logic Cc: # 3.3.x - Signed-off-by: Ingo Molnar + Signed-off-by: Ingo Molnar + +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: # 3.3.x- - The tag has the meaning of: +The tag has the meaning of: + +.. code-block:: none + git cherry-pick - 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