[PATCH v5] README: restructure with role-based documentation and guidelines

[PATCH v5] README: restructure with role-based documentation and guidelines

[Sasha Levin]

Reorganize README to provide targeted documentation paths for different user
roles including developers, researchers, security experts, and maintainers.

Add quick start section and essential docs links.

Signed-off-by: Sasha Levin <sashal@kernel.org>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Kees Cook <kees@kernel.org>
---

Changes since v4:

 - Remove explicit reference to GPLv2
 - Fix up the commit message to drop AI blurb

 README | 160 +++++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 149 insertions(+), 11 deletions(-)

diff --git a/README b/README
index fd903645e6de0..1fc993d7cf07e 100644
--- a/README
+++ b/README
@@ -1,18 +1,156 @@
 Linux kernel
 ============
 
-There are several guides for kernel developers and users. These guides can
-be rendered in a number of formats, like HTML and PDF. Please read
-Documentation/admin-guide/README.rst first.
+The Linux kernel is the core of any Linux operating system. It manages hardware,
+system resources, and provides the fundamental services for all other software.
 
-In order to build the documentation, use ``make htmldocs`` or
-``make pdfdocs``.  The formatted documentation can also be read online at:
+Quick Start
+-----------
 
-    https://www.kernel.org/doc/html/latest/
+* Report a bug: See Documentation/admin-guide/reporting-issues.rst
+* Get the latest kernel: https://kernel.org
+* Build the kernel: See Documentation/admin-guide/quickly-build-trimmed-linux.rst
+* Join the community: https://lore.kernel.org/
 
-There are various text files in the Documentation/ subdirectory,
-several of them using the reStructuredText markup notation.
+Essential Documentation
+-----------------------
 
-Please read the Documentation/process/changes.rst file, as it contains the
-requirements for building and running the kernel, and information about
-the problems which may result by upgrading your kernel.
+All users should be familiar with:
+
+* Building requirements: Documentation/process/changes.rst
+* Code of Conduct: Documentation/process/code-of-conduct.rst
+* License: See COPYING
+
+Documentation can be built with make htmldocs or viewed online at:
+https://www.kernel.org/doc/html/latest/
+
+
+Who Are You?
+============
+
+Find your role below:
+
+* New Kernel Developer - Getting started with kernel development
+* Academic Researcher - Studying kernel internals and architecture
+* Security Expert - Hardening and vulnerability analysis
+* Backport/Maintenance Engineer - Maintaining stable kernels
+* System Administrator - Configuring and troubleshooting
+* Maintainer - Leading subsystems and reviewing patches
+* Hardware Vendor - Writing drivers for new hardware
+* Distribution Maintainer - Packaging kernels for distros
+
+
+For Specific Users
+==================
+
+New Kernel Developer
+--------------------
+
+Welcome! Start your kernel development journey here:
+
+* Getting Started: Documentation/process/development-process.rst
+* Your First Patch: Documentation/process/submitting-patches.rst
+* Coding Style: Documentation/process/coding-style.rst
+* Build System: Documentation/kbuild/index.rst
+* Development Tools: Documentation/dev-tools/index.rst
+* Kernel Hacking Guide: Documentation/kernel-hacking/hacking.rst
+* Core APIs: Documentation/core-api/index.rst
+
+Academic Researcher
+-------------------
+
+Explore the kernel's architecture and internals:
+
+* Researcher Guidelines: Documentation/process/researcher-guidelines.rst
+* Memory Management: Documentation/mm/index.rst
+* Scheduler: Documentation/scheduler/index.rst
+* Networking Stack: Documentation/networking/index.rst
+* Filesystems: Documentation/filesystems/index.rst
+* RCU (Read-Copy Update): Documentation/RCU/index.rst
+* Locking Primitives: Documentation/locking/index.rst
+* Power Management: Documentation/power/index.rst
+
+Security Expert
+---------------
+
+Security documentation and hardening guides:
+
+* Security Documentation: Documentation/security/index.rst
+* LSM Development: Documentation/security/lsm-development.rst
+* Self Protection: Documentation/security/self-protection.rst
+* Reporting Vulnerabilities: Documentation/process/security-bugs.rst
+* CVE Procedures: Documentation/process/cve.rst
+* Embargoed Hardware Issues: Documentation/process/embargoed-hardware-issues.rst
+* Security Features: Documentation/userspace-api/seccomp_filter.rst
+
+Backport/Maintenance Engineer
+-----------------------------
+
+Maintain and stabilize kernel versions:
+
+* Stable Kernel Rules: Documentation/process/stable-kernel-rules.rst
+* Backporting Guide: Documentation/process/backporting.rst
+* Applying Patches: Documentation/process/applying-patches.rst
+* Subsystem Profile: Documentation/maintainer/maintainer-entry-profile.rst
+* Git for Maintainers: Documentation/maintainer/configure-git.rst
+
+System Administrator
+--------------------
+
+Configure, tune, and troubleshoot Linux systems:
+
+* Admin Guide: Documentation/admin-guide/index.rst
+* Kernel Parameters: Documentation/admin-guide/kernel-parameters.rst
+* Sysctl Tuning: Documentation/admin-guide/sysctl/index.rst
+* Tracing/Debugging: Documentation/trace/index.rst
+* Performance Security: Documentation/admin-guide/perf-security.rst
+* Hardware Monitoring: Documentation/hwmon/index.rst
+
+Maintainer
+----------
+
+Lead kernel subsystems and manage contributions:
+
+* Maintainer Handbook: Documentation/maintainer/index.rst
+* Pull Requests: Documentation/maintainer/pull-requests.rst
+* Managing Patches: Documentation/maintainer/modifying-patches.rst
+* Rebasing and Merging: Documentation/maintainer/rebasing-and-merging.rst
+* Development Process: Documentation/process/maintainer-handbooks.rst
+* Maintainer Entry Profile: Documentation/maintainer/maintainer-entry-profile.rst
+* Git Configuration: Documentation/maintainer/configure-git.rst
+
+Hardware Vendor
+---------------
+
+Write drivers and support new hardware:
+
+* Driver API Guide: Documentation/driver-api/index.rst
+* Driver Model: Documentation/driver-api/driver-model/driver.rst
+* Device Drivers: Documentation/driver-api/infrastructure.rst
+* Bus Types: Documentation/driver-api/driver-model/bus.rst
+* Device Tree Bindings: Documentation/devicetree/bindings/
+* Power Management: Documentation/driver-api/pm/index.rst
+* DMA API: Documentation/core-api/dma-api.rst
+
+Distribution Maintainer
+-----------------------
+
+Package and distribute the kernel:
+
+* Stable Kernel Rules: Documentation/process/stable-kernel-rules.rst
+* ABI Documentation: Documentation/ABI/README
+* Kernel Configuration: Documentation/kbuild/kconfig.rst
+* Module Signing: Documentation/admin-guide/module-signing.rst
+* Kernel Parameters: Documentation/admin-guide/kernel-parameters.rst
+* Tainted Kernels: Documentation/admin-guide/tainted-kernels.rst
+
+
+
+Communication and Support
+=========================
+
+* Mailing Lists: https://lore.kernel.org/
+* IRC: #kernelnewbies on irc.oftc.net
+* Bugzilla: https://bugzilla.kernel.org/
+* MAINTAINERS file: Lists subsystem maintainers and mailing lists
+* Email Clients: Documentation/process/email-clients.rst
-- 
2.51.0

Re: [PATCH v5] README: restructure with role-based documentation and guidelines

[Joe Perches]

On Fri, 2025-11-21 at 13:00 -0500, Sasha Levin wrote:
> Reorganize README to provide targeted documentation paths for different user
> roles including developers, researchers, security experts, and maintainers.

Thank you Sasha.  Looks great.

Re: [PATCH v5] README: restructure with role-based documentation and guidelines

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 410 bytes --]

On Fri, Nov 21, 2025 at 01:00:09PM -0500, Sasha Levin wrote:
> Reorganize README to provide targeted documentation paths for different user
> roles including developers, researchers, security experts, and maintainers.
> 
> Add quick start section and essential docs links.

LGTM, thanks!

Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH v5] README: restructure with role-based documentation and guidelines

[SeongJae Park]

On Fri, 21 Nov 2025 13:00:09 -0500 Sasha Levin <sashal@kernel.org> wrote:

> Reorganize README to provide targeted documentation paths for different user
> roles including developers, researchers, security experts, and maintainers.
> 
> Add quick start section and essential docs links.
> 
> Signed-off-by: Sasha Levin <sashal@kernel.org>
> Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
> Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> Reviewed-by: Kees Cook <kees@kernel.org>

Reviewed-by: SeongJae Park <sj@kernel.org>

> ---
> 
> Changes since v4:
> 
>  - Remove explicit reference to GPLv2
>  - Fix up the commit message to drop AI blurb
> 
>  README | 160 +++++++++++++++++++++++++++++++++++++++++++++++++++++----
>  1 file changed, 149 insertions(+), 11 deletions(-)
> 
> diff --git a/README b/README
> index fd903645e6de0..1fc993d7cf07e 100644
> --- a/README
> +++ b/README
> @@ -1,18 +1,156 @@
[...]
> +Documentation can be built with make htmldocs or viewed online at:
> +https://www.kernel.org/doc/html/latest/
> +
> +
> +Who Are You?
> +============
> +
> +Find your role below:
> +
> +* New Kernel Developer - Getting started with kernel development
> +* Academic Researcher - Studying kernel internals and architecture
> +* Security Expert - Hardening and vulnerability analysis
> +* Backport/Maintenance Engineer - Maintaining stable kernels
> +* System Administrator - Configuring and troubleshooting
> +* Maintainer - Leading subsystems and reviewing patches
> +* Hardware Vendor - Writing drivers for new hardware
> +* Distribution Maintainer - Packaging kernels for distros
> +
> +
> +For Specific Users
> +==================
> +
> +New Kernel Developer
> +--------------------
[...]
> +Distribution Maintainer
> +-----------------------
> +
> +Package and distribute the kernel:
> +
> +* Stable Kernel Rules: Documentation/process/stable-kernel-rules.rst
> +* ABI Documentation: Documentation/ABI/README
> +* Kernel Configuration: Documentation/kbuild/kconfig.rst
> +* Module Signing: Documentation/admin-guide/module-signing.rst
> +* Kernel Parameters: Documentation/admin-guide/kernel-parameters.rst
> +* Tainted Kernels: Documentation/admin-guide/tainted-kernels.rst
> +
> +
> +
> +Communication and Support
> +=========================

Nit.  Having only two blank lines above this section would make this document
look more consistent.


Thanks,
SJ

[...]

Re: [PATCH v5] README: restructure with role-based documentation and guidelines

[Jonathan Corbet]

Sasha Levin <sashal@kernel.org> writes:

> Reorganize README to provide targeted documentation paths for different user
> roles including developers, researchers, security experts, and maintainers.
>
> Add quick start section and essential docs links.
>
> Signed-off-by: Sasha Levin <sashal@kernel.org>
> Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
> Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> Reviewed-by: Kees Cook <kees@kernel.org>
> ---
>
> Changes since v4:
>
>  - Remove explicit reference to GPLv2
>  - Fix up the commit message to drop AI blurb
>
>  README | 160 +++++++++++++++++++++++++++++++++++++++++++++++++++++----
>  1 file changed, 149 insertions(+), 11 deletions(-)

Applied, thanks.

jon