From 9b4ebd98da9112f974a6db58555a33eb1bd7c0b0 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 26 Oct 2016 16:34:09 -0600 Subject: docs: Apply some basic organization to the process guide Put like documents together, with the essential ones at the top, and split the TOC into sections. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/process/changes.rst | 2 +- Documentation/process/index.rst | 37 ++++++++++++++++++++++++++++--------- 2 files changed, 29 insertions(+), 10 deletions(-) (limited to 'Documentation/process') diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst index 22797a15dc24..56ce66114665 100644 --- a/Documentation/process/changes.rst +++ b/Documentation/process/changes.rst @@ -1,6 +1,6 @@ .. _changes: -Minimal requerements to compile the Kernel +Minimal requirements to compile the Kernel ++++++++++++++++++++++++++++++++++++++++++ Intro diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index 6ee818752474..0cbc62adbbb1 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -4,29 +4,48 @@ \renewcommand\thesubsection* -Linux Kernel Development Documentation -====================================== +Working with the kernel development community +============================================= -Contents: +So you want to be a Linux kernel developer? Welcome! While there is a lot +to be learned about the kernel in a technical sense, it is also important +to learn about how our community works. Reading these documents will make +it much easier for you to get your changes merged with a minimum of +trouble. + +Below are the essential guides that every developer should read. .. toctree:: :maxdepth: 2 howto - changes - coding-style + code-of-conflict + development-process submitting-patches + coding-style + email-clients + +Other guides to the community that are of interest to most developers are: + +.. toctree:: + :maxdepth: 2 + + changes submitting-drivers stable-api-nonsense management-style stable-kernel-rules + submit-checklist kernel-docs + +These are some overall technical guides that have been put here for now for +lack of a better place. + +.. toctree:: + :maxdepth: 2 + applying-patches - email-clients - submit-checklist - code-of-conflict adding-syscalls magic-number volatile-considered-harmful - development-process -- cgit v1.2.3 From 89edeedd61e8faa4e092f3797606739317abeb6c Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 26 Oct 2016 16:37:53 -0600 Subject: docs: Tweak submitting-patches.rst formatting The main goal here was to get the subsections to show in the TOC as they do for all the other documents. Also call out the DCO in the section title since it's important. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/process/submitting-patches.rst | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) (limited to 'Documentation/process') diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index b4cf8f375184..3e10719fee35 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -1,7 +1,7 @@ .. _submittingpatches: -How to Get Your Change Into the Linux Kernel or Care And Operation Of Your Linus Torvalds -========================================================================================= +Submitting patches: the essential guide to getting your code into the kernel +============================================================================ For a person or company who wishes to submit a change to the Linux kernel, the process can sometimes be daunting if you're not familiar @@ -24,10 +24,6 @@ of the mechanical work done for you, though you'll still need to prepare and document a sensible set of patches. In general, use of ``git`` will make your life as a kernel developer easier. -Creating and Sending your Change -******************************** - - 0) Obtain a current source tree ------------------------------- @@ -417,8 +413,8 @@ e-mail discussions. -11) Sign your work ------------------- +11) Sign your work — the Developer's Certificate of Origin +---------------------------------------------------------- To improve tracking of who did what, especially with patches that can percolate to their final resting place in the kernel through several @@ -803,8 +799,8 @@ command like this will do the trick:: git request-pull master git://my.public.tree/linux.git my-signed-tag -REFERENCES -********** +References +---------- Andrew Morton, "The perfect patch" (tpp). -- cgit v1.2.3 From be4612447b3721a9a9f14ea5189217d69bc83078 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 26 Oct 2016 16:41:05 -0600 Subject: docs: Collapse the process guide TOC I believe this makes the page as a whole more approachable. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/process/index.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'Documentation/process') diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index 0cbc62adbbb1..0557144cef2b 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -16,7 +16,7 @@ trouble. Below are the essential guides that every developer should read. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 howto code-of-conflict @@ -28,7 +28,7 @@ Below are the essential guides that every developer should read. Other guides to the community that are of interest to most developers are: .. toctree:: - :maxdepth: 2 + :maxdepth: 1 changes submitting-drivers @@ -42,7 +42,7 @@ These are some overall technical guides that have been put here for now for lack of a better place. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 applying-patches adding-syscalls -- cgit v1.2.3 From 31b24bee33572031632c33091bb73ed0e949c53a Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 26 Oct 2016 16:45:29 -0600 Subject: docs: add a warning to submitting-drivers.rst This is crufty stuff and should maybe just be deleted, but I'm not quite ready to do that yet. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/process/submitting-drivers.rst | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'Documentation/process') diff --git a/Documentation/process/submitting-drivers.rst b/Documentation/process/submitting-drivers.rst index 0939d018c289..afb82ee0cbea 100644 --- a/Documentation/process/submitting-drivers.rst +++ b/Documentation/process/submitting-drivers.rst @@ -8,6 +8,14 @@ various kernel trees. Note that if you are interested in video card drivers you should probably talk to XFree86 (http://www.xfree86.org/) and/or X.Org (http://x.org/) instead. +.. note:: + + This document is old and has seen little maintenance in recent years; it + should probably be updated or, perhaps better, just deleted. Most of + what is here can be found in the other development documents anyway. + + Oh, and we don't really recommend submitting changes to XFree86 :) + Also read the Documentation/process/submitting-patches.rst document. -- cgit v1.2.3 From 67972a539e9ff1a3ed794c463c4e544442df693e Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 26 Oct 2016 16:48:36 -0600 Subject: docs: Add a warning to applying-patches.rst This is ancient stuff and we don't do things this way anymore. In the absence of simply deleting the document, at least add a warning to it. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/process/applying-patches.rst | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'Documentation/process') diff --git a/Documentation/process/applying-patches.rst b/Documentation/process/applying-patches.rst index abd7dc7ae240..87825cf96f33 100644 --- a/Documentation/process/applying-patches.rst +++ b/Documentation/process/applying-patches.rst @@ -9,6 +9,10 @@ Original by: Last update: 2016-09-14 +.. note:: + + This document is obsolete. In most cases, rather than using ``patch`` + manually, you'll almost certainly want to look at using Git instead. A frequently asked question on the Linux Kernel Mailing List is how to apply a patch to the kernel or, more specifically, what base kernel a patch for -- cgit v1.2.3