Rework the top-level process page
Subsystems (2)
Jonathan Corbet
maintainerRFC PATCH 1/1 Rework the top-level process page
The process book is arguably the most important documentation we have; the top three trafficked pages on docs.kernel.org are found here. Make a beginning effort to impose a more useful organization on this page to ease developers into the community.
---
This is a version of the reworked page I showed briefly during the kernel-summit documentation session. Perhaps more useful than the patch itself is the rendered version of the page, which can be seen at:
https://static.lwn.net/kerneldoc/process/index.html
There is a lot to do to turn this book into a coherent set of documentation, but this seems like a plausible step in that direction.
Documentation/process/index.rst | 84 ++++++++++++++++++++++++--------- 1 file changed, 63 insertions(+), 21 deletions(-)
Documentation/process/index.rst +63 -21
@@ -15,49 +15,96 @@ 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. +An introduction to how kernel development works +----------------------------------------------- + +Read these documents first: an understanding of the material here will ease +your entry into the kernel community. .. toctree:: :maxdepth: 1 - license-rules howto - code-of-conduct - code-of-conduct-interpretation development-process submitting-patches - handling-regressions + submit-checklist + +Tools and technical guides for kernel developers +------------------------------------------------ + +This is a collection of material that kernel developers should be familiar +with. + +.. toctree:: + :maxdepth: 1 + + changes programming-language coding-style - maintainer-handbooks maintainer-pgp-guide email-clients + applying-patches + backporting + adding-syscalls + volatile-considered-harmful + botching-up-ioctls + +Policy guides and developer statements +-------------------------------------- + +These are the rules that we try to live by in the kernel community (and +beyond). + +.. toctree:: + :maxdepth: 1 + + license-rules + code-of-conduct + code-of-conduct-interpretation + contribution-maturity-model kernel-enforcement-statement kernel-driver-statement + stable-api-nonsense + stable-kernel-rules + management-style + researcher-guidelines -For security issues, see: +Dealing with bugs +----------------- + +Bugs are a fact of life; it is important that we handle them properly. +The documents below describe our policies around the handling of a couple +of special classes of bugs: regressions and security problems. .. toctree:: :maxdepth: 1 + handling-regressions security-bugs embargoed-hardware-issues -Other guides to the community that are of interest to most developers are: +Maintainer information +---------------------- + +How to find the people who will accept your patches. + +.. toctree:: + :maxdepth: 1 + + maintainer-handbooks + maintainers + +Other material +-------------- + +Here are some other guides to the community that are of interest to most +developers are: .. toctree:: :maxdepth: 1 - changes - stable-api-nonsense - management-style - stable-kernel-rules - submit-checklist kernel-docs deprecated - maintainers - researcher-guidelines - contribution-maturity-model These are some overall technical guides that have been put here for now for lack of a better place.
@@ -65,12 +112,7 @@ lack of a better place. .. toctree:: :maxdepth: 1 - applying-patches - backporting - adding-syscalls magic-number - volatile-considered-harmful - botching-up-ioctls clang-format ../arch/riscv/patch-acceptance ../core-api/unaligned-memory-access
Signature · 1 line
2.42.0
Randy Dunlap
reviewerDocumentation/process/index.rst to learn about how our community works. Reading these documents will make · line 101
Quoted 5 lines · Jonathan Corbet
Documentation/process/index.rst +5
-0+Other material +-------------- + +Here are some other guides to the community that are of interest to most +developers are:
eh?
Signature · 1 line
~Randy
Quoted 7 lines · Jonathan Corbet
Documentation/process/index.rst +5
-0+An introduction to how kernel development works +----------------------------------------------- + +Read these documents first: an understanding of the material here will ease +your entry into the kernel community. .. toctree::
Documentation/process/index.rst to learn about how our community works. Reading these documents will make · line 30
Quoted 10 lines
Documentation/process/index.rst +1
-4:maxdepth: 1 - license-rules howto - code-of-conduct - code-of-conduct-interpretation development-process submitting-patches - handling-regressions + submit-checklist
I feel the policy section should come first. Yes, howto is important, but putting the policy first means it's more important.
Quoted 19 lines
Documentation/process/index.rst +17
-0+Policy guides and developer statements +-------------------------------------- + +These are the rules that we try to live by in the kernel community (and +beyond). + +.. toctree:: + :maxdepth: 1 + + license-rules + code-of-conduct + code-of-conduct-interpretation + contribution-maturity-model kernel-enforcement-statement kernel-driver-statement + stable-api-nonsense + stable-kernel-rules + management-style + researcher-guidelines
Quoted 9 lines · Jonathan Corbet
The process book is arguably the most important documentation we have; the top three trafficked pages on docs.kernel.org are found here. Make a beginning effort to impose a more useful organization on this page to ease developers into the community.
---
This is a version of the reworked page I showed briefly during the kernel-summit documentation session. Perhaps more useful than the patch itself is the rendered version of the page, which can be seen at:
Quoted 4 lines
https://static.lwn.net/kerneldoc/process/index.html
There is a lot to do to turn this book into a coherent set of documentation, but this seems like a plausible step in that direction.
I think the reworked page is clearly an improvement.
The following is not really a comment on your patch specifically, but on the page in general:
"""
Tools and technical guides for kernel developers
This is a collection of material that kernel developers should be familiar with.
Minimal requirements to compile the Kernel Programming Language
Linux kernel coding style
Kernel Maintainer PGP guide
Email clients info for Linux
Applying Patches To The Linux Kernel Backporting and conflict resolution Adding a New System Call
Why the "volatile" type class should not be used (How to avoid) Botching up ioctls
"""
I think the last three links probably belong somewhere else -- for me, those are not process-related but actual kernel-code-technical information. The same goes for "Unaligned Memory Accesses" at the bottom of the page.
How about putting these somewhere under kernel-hacking/ (AKA "Kernel Hacking Guides")?
Vegard