Message-ID: <20251119084353.658db390@foz.lan>
Date: Wed, 19 Nov 2025 08:43:53 +0100
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Sasha Levin <sashal@...nel.org>
Cc: corbet@....net, linux-doc@...r.kernel.org, josh@...htriplett.org,
 kees@...nel.org, konstantin@...uxfoundation.org,
 linux-kernel@...r.kernel.org, rostedt@...dmis.org,
 workflows@...r.kernel.org, joe@...ches.com, rdunlap@...radead.org
Subject: Re: [PATCH v4] README: restructure with role-based documentation
 and guidelines

Em Tue, 18 Nov 2025 21:38:32 -0500
Sasha Levin <sashal@...nel.org> escreveu:

> Reorganize README to provide targeted documentation paths for different user
> roles including developers, researchers, security experts, maintainers, and AI
> coding assistants. Add quick start section and essential docs links.
> 
> Include proper attribution requirements for AI-assisted contributions using
> Assisted-by tags with agent details and tools used.
> 
> Signed-off-by: Sasha Levin <sashal@...nel.org>

I liked the new version. Yet, IMO License requires some changes. After
that, feel free to add:

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>

> ---
> 
> Changes since v3:
> 
>  - No AI hype :)
>  - Link to a guide for building the kernel
> 
> 
>  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

Perhaps you might add a link to Documentation/process/security-bugs.rst
as well, although it is already there at 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: COPYING (GPLv2)

Hmm... "GPLv2" doesn't fit all, as it is GPL-2.0 WITH Linux-syscall-note,
plus, as stated on COPYING:

	"In addition, other licenses may also apply."

As we don't want to repeat the entire COPYING text here, better
to just point to the file, e.g.

	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



Thanks,
Mauro

Powered by blists - more mailing lists