From dca22a63fd036c3ebb50212060eba0080f178126 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 08:51:05 -0300 Subject: docs-rst: add inter-document cross references Add cross references for the development process documents that were converted to ReST: Documentation/SubmitChecklist Documentation/SubmittingDrivers Documentation/SubmittingPatches Documentation/development-process/development-process.rst Documentation/stable_kernel_rules.txt Signed-off-by: Mauro Carvalho Chehab Acked-by: Greg Kroah-Hartman Signed-off-by: Jonathan Corbet --- Documentation/SubmitChecklist | 10 +++++---- Documentation/SubmittingDrivers | 7 ++++--- Documentation/SubmittingPatches | 24 ++++++++++++++-------- .../development-process/development-process.rst | 2 ++ Documentation/stable_kernel_rules.txt | 7 +++++-- 5 files changed, 32 insertions(+), 18 deletions(-) diff --git a/Documentation/SubmitChecklist b/Documentation/SubmitChecklist index 22a370ff34e5..894289b22b15 100644 --- a/Documentation/SubmitChecklist +++ b/Documentation/SubmitChecklist @@ -1,3 +1,5 @@ +.. _submitchecklist: + Linux Kernel patch submission checklist ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -5,7 +7,7 @@ Here are some basic things that developers should do if they want to see their kernel patch submissions accepted more quickly. These are all above and beyond the documentation that is provided in -Documentation/SubmittingPatches +:ref:`Documentation/SubmittingPatches ` and elsewhere regarding submitting Linux kernel patches. @@ -28,8 +30,8 @@ and elsewhere regarding submitting Linux kernel patches. 4) ppc64 is a good architecture for cross-compilation checking because it tends to use ``unsigned long`` for 64-bit quantities. -5: Check your patch for general style as detailed in - Documentation/CodingStyle. +5) Check your patch for general style as detailed in + :ref:`Documentation/CodingStyle `. Check for trivial violations with the patch style checker prior to submission (``scripts/checkpatch.pl``). You should be able to justify all violations that remain in @@ -54,7 +56,7 @@ and elsewhere regarding submitting Linux kernel patches. but any one function that uses more than 512 bytes on the stack is a candidate for change. -11: Include :ref:`kernel-doc ` to document global kernel APIs. +11) Include :ref:`kernel-doc ` to document global kernel APIs. (Not required for static functions, but OK there also.) Use ``make htmldocs`` or ``make pdfdocs`` to check the :ref:`kernel-doc ` and fix any issues. diff --git a/Documentation/SubmittingDrivers b/Documentation/SubmittingDrivers index 2ac931645e53..252b77a23fad 100644 --- a/Documentation/SubmittingDrivers +++ b/Documentation/SubmittingDrivers @@ -40,9 +40,9 @@ Linux 2.4: maintainer does not respond or you cannot find the appropriate maintainer then please contact Willy Tarreau . -Linux 2.6: +Linux 2.6 and upper: The same rules apply as 2.4 except that you should follow linux-kernel - to track changes in API's. The final contact point for Linux 2.6 + to track changes in API's. The final contact point for Linux 2.6+ submissions is Andrew Morton. What Criteria Determine Acceptance @@ -73,7 +73,8 @@ Interfaces: Code: Please use the Linux style of code formatting as documented - in Documentation/CodingStyle. If you have sections of code + in :ref:`Documentation/CodingStyle `. + If you have sections of code that need to be in other formats, for example because they are shared with a windows driver kit and you want to maintain them just once separate them out nicely and note diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 9c3dfa7babf3..36f1dedc944c 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -10,10 +10,12 @@ can greatly increase the chances of your change being accepted. This document contains a large number of suggestions in a relatively terse format. For detailed information on how the kernel development process -works, see Documentation/development-process. Also, read -Documentation/SubmitChecklist for a list of items to check before +works, see :ref:`Documentation/development-process `. +Also, read :ref:`Documentation/SubmitChecklist ` +for a list of items to check before submitting code. If you are submitting a driver, also read -Documentation/SubmittingDrivers; for device tree binding patches, read +:ref:`Documentation/SubmittingDrivers `; +for device tree binding patches, read Documentation/devicetree/bindings/submitting-patches.txt. Many of these steps describe the default behavior of the ``git`` version @@ -235,7 +237,9 @@ then only post say 15 or so at a time and wait for review and integration. --------------------------- Check your patch for basic style violations, details of which can be -found in Documentation/CodingStyle. Failure to do so simply wastes +found in +:ref:`Documentation/CodingStyle `. +Failure to do so simply wastes the reviewers time and will get your patch rejected, probably without even being read. @@ -300,8 +304,9 @@ toward the stable maintainers by putting a line like this:: Cc: stable@vger.kernel.org into the sign-off area of your patch (note, NOT an email recipient). You -should also read Documentation/stable_kernel_rules.txt in addition to this -file. +should also read +:ref:`Documentation/stable_kernel_rules.txt ` +in addition to this file. Note, however, that some subsystem maintainers want to come to their own conclusions on which patches should go to the stable trees. The networking @@ -358,8 +363,9 @@ decreasing the likelihood of your MIME-attached change being accepted. Exception: If your mailer is mangling patches then someone may ask you to re-send them using MIME. -See Documentation/email-clients.txt for hints about configuring -your e-mail client so that it sends your patches untouched. +See :ref:`Documentation/email-clients.txt ` +for hints about configuring your e-mail client so that it sends your patches +untouched. 7) E-mail size -------------- @@ -823,7 +829,7 @@ NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! Kernel Documentation/CodingStyle: - + :ref:`Documentation/CodingStyle ` Linus Torvalds's mail on the canonical patch format: diff --git a/Documentation/development-process/development-process.rst b/Documentation/development-process/development-process.rst index d431a1098875..bd1399f7202a 100644 --- a/Documentation/development-process/development-process.rst +++ b/Documentation/development-process/development-process.rst @@ -1,3 +1,5 @@ +.. _development_process_main: + A guide to the Kernel Development Process ========================================= diff --git a/Documentation/stable_kernel_rules.txt b/Documentation/stable_kernel_rules.txt index 1eba72708c7f..4d82e31b7958 100644 --- a/Documentation/stable_kernel_rules.txt +++ b/Documentation/stable_kernel_rules.txt @@ -26,7 +26,9 @@ Rules on what kind of patches are accepted, and which ones are not, into the race can be exploited is also provided. - It cannot contain any "trivial" fixes in it (spelling changes, whitespace cleanups, etc). - - It must follow the Documentation/SubmittingPatches rules. + - It must follow the + :ref:`Documentation/SubmittingPatches ` + rules. - It or an equivalent fix must already exist in Linus' tree (upstream). @@ -37,7 +39,8 @@ Procedure for submitting patches to the -stable tree submission guidelines as described in Documentation/networking/netdev-FAQ.txt - Security patches should not be handled (solely) by the -stable review - process but should follow the procedures in Documentation/SecurityBugs. + process but should follow the procedures in + :ref:`Documentation/SecurityBugs `. For all other submissions, choose one of the following procedures ----------------------------------------------------------------- -- cgit v1.2.3