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@kernel.org>
---
README | 184 +++++++++++++++++++++++++++++++++++++++++++++++++++++----
1 file changed, 173 insertions(+), 11 deletions(-)
diff --git a/README b/README
index fd903645e6de..251677d7cd09 100644
--- a/README
+++ b/README
@@ -1,18 +1,180 @@
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: make defconfig && make -j$(nproc)
+* 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)
+
+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
+* Agentic Coding - AI assistants working with kernel code
+
+
+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
+
+Agentic Coding
+--------------
+
+Essential guidelines for AI coding assistants:
+
+* How to Do Kernel Development: Documentation/process/howto.rst
+* Coding Style: Documentation/process/coding-style.rst
+* Submitting Patches: Documentation/process/submitting-patches.rst
+* Submit Checklist: Documentation/process/submit-checklist.rst
+* Programming Language: Documentation/process/programming-language.rst
+
+Critical Requirements:
+
+* License: Use proper SPDX identifiers per
+ Documentation/process/license-rules.rst; kernel code is generally
+ GPL-2.0-only unless documented exceptions apply (see COPYING)
+* Signed-off-by: Agents MUST NOT add Signed-off-by tags
+ (Only humans can legally certify code submission rights)
+* Attribution: Agents MUST add Assisted-by tag:
+ Assisted-by: $AGENT_NAME-$AGENT_MODEL-$AGENT_VERSION $TOOL1 $TOOL2 ...
+ Examples:
+ - Assisted-by: Claude-claude-3-opus-20240229 checkpatch git-bisect
+ - Assisted-by: GitHub-Copilot-GPT-4-v1.0.0 coccinelle sparse
+
+
+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.39.5On Sat, Aug 09, 2025 at 07:40:07PM -0400, Sasha Levin wrote: > 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. This looks really great; thank you for writing it all out! > +* Attribution: Agents MUST add Assisted-by tag: > + Assisted-by: $AGENT_NAME-$AGENT_MODEL-$AGENT_VERSION $TOOL1 $TOOL2 ... > + Examples: > + - Assisted-by: Claude-claude-3-opus-20240229 checkpatch git-bisect > + - Assisted-by: GitHub-Copilot-GPT-4-v1.0.0 coccinelle sparse I think "git" and "checkpatch" getting called out in Assisted-by is overkill/redundant. Devs are going to use git constantly, and checkpatch is already explicitly called out as a minimum standard linter for submitting patches. As for agent formatting, it's hard to parse "-" separators if they're already used within the model/version. How about : or ; ? -- Kees Cook
Hi Sasha,
On Sun, 10 Aug 2025 at 10:09, Sasha Levin <sashal@kernel.org> wrote:
> 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@kernel.org>
Thanks for your patch!
> --- a/README
> +++ b/README
> +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
Kernel Maintainer?
Driver/Subsystem Maintainer?
> +* Hardware Vendor - Writing drivers for new hardware
> +* Distribution Maintainer - Packaging kernels for distros
> +* Agentic Coding - AI assistants working with kernel code
Given the extensive split, what about normal (existing) kernel
developers?
Gr{oetje,eeting}s,
Geert
--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org
In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
-- Linus Torvalds
On Mon, Aug 11, 2025 at 10:22:34AM +0200, Geert Uytterhoeven wrote: >Hi Sasha, > >On Sun, 10 Aug 2025 at 10:09, Sasha Levin <sashal@kernel.org> wrote: >> 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@kernel.org> > >Thanks for your patch! > >> --- a/README >> +++ b/README > >> +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 > >Kernel Maintainer? >Driver/Subsystem Maintainer? I tried to use similar terms to the ones used by the rest of our docs. In this case, the CoC interpertation actually defines this term :) The Code of Conduct uses the term "maintainers" numerous times. In the kernel community, a "maintainer" is anyone who is responsible for a subsystem, driver, or file, and is listed in the MAINTAINERS file in the kernel source tree. So I just went with "Maintainer". >> +* Hardware Vendor - Writing drivers for new hardware >> +* Distribution Maintainer - Packaging kernels for distros >> +* Agentic Coding - AI assistants working with kernel code > >Given the extensive split, what about normal (existing) kernel >developers? Those people don't read the docs anyway :p How about something like: Existing Kernel Developer ------------------------- Continue advancing your kernel development expertise: * Locking and Concurrency: Documentation/locking/index.rst * RCU (Read-Copy Update): Documentation/RCU/index.rst * Subsystem APIs: Documentation/driver-api/index.rst * Performance Analysis: Documentation/trace/index.rst * Testing Infrastructure: Documentation/dev-tools/testing-overview.rst * Patch Series Management: Documentation/process/5.Posting.rst * Maintainer Handbooks: Documentation/process/maintainer-handbooks.rst * Cross-Architecture Development: Documentation/arch/index.rst * Kernel Debugging: Documentation/process/debugging/kgdb.rst -- Thanks, Sasha
On 8/9/25 4:40 PM, Sasha Levin wrote: > 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@kernel.org> > --- > README | 184 +++++++++++++++++++++++++++++++++++++++++++++++++++++---- > 1 file changed, 173 insertions(+), 11 deletions(-) > I like it. Thanks. Reviewed-by: Randy Dunlap <rdunlap@infradead.org> -- ~Randy
On Sat, 2025-08-09 at 19:40 -0400, Sasha Levin wrote:
> 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.
Nicely done.
Perhaps the 'Assisted-by:' tag should not be limited to AI
assistance but could also be used when accepted notes were
given on any revised patch submission.
Oh, and maybe a checkpatch update like this?
---
scripts/checkpatch.pl | 1 +
1 file changed, 1 insertion(+)
diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
index e722dd6fa8ef3..d17661141da79 100755
--- a/scripts/checkpatch.pl
+++ b/scripts/checkpatch.pl
@@ -641,6 +641,7 @@ our $signature_tags = qr{(?xi:
Reviewed-by:|
Reported-by:|
Suggested-by:|
+ Assisted-by:|
To:|
Cc:
)};
On Sun, Aug 10, 2025 at 08:44:58AM -0700, Joe Perches wrote:
>On Sat, 2025-08-09 at 19:40 -0400, Sasha Levin wrote:
>> 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.
>
>Nicely done.
Thanks Joe!
>Perhaps the 'Assisted-by:' tag should not be limited to AI
>assistance but could also be used when accepted notes were
>given on any revised patch submission.
The suggestions from the previous patches around expanding this to be a
list of tools rather than just "AI" made sense, this is the example I
gave in the cover letter:
Assisted-by: Claude-claude-3-opus-20240229 checkpatch
I find something like that useful because it tells me from the get-go
that the submitter ran checkpatch on it (without having to spend a line
in the commit message saying the same).
I'm not sure about mixing human feedback into this, it might be
difficult to interpert it later.
It might work more naturally as an extension of Reviewed-by?
Reviewed-by: Developer A <a@b.c> # Improved the XYZ algorithm
>Oh, and maybe a checkpatch update like this?
>---
> scripts/checkpatch.pl | 1 +
> 1 file changed, 1 insertion(+)
>
>diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
>index e722dd6fa8ef3..d17661141da79 100755
>--- a/scripts/checkpatch.pl
>+++ b/scripts/checkpatch.pl
>@@ -641,6 +641,7 @@ our $signature_tags = qr{(?xi:
> Reviewed-by:|
> Reported-by:|
> Suggested-by:|
>+ Assisted-by:|
> To:|
> Cc:
> )};
Yup, makes sense! I'll start including checkpatch updates going forward.
--
Thanks,
Sasha
On Sun, 2025-08-10 at 12:46 -0400, Sasha Levin wrote:
> On Sun, Aug 10, 2025 at 08:44:58AM -0700, Joe Perches wrote:
> > On Sat, 2025-08-09 at 19:40 -0400, Sasha Levin wrote:
> > > 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.
> >
> > Nicely done.
>
> Thanks Joe!
>
> > Perhaps the 'Assisted-by:' tag should not be limited to AI
> > assistance but could also be used when accepted notes were
> > given on any revised patch submission.
>
> The suggestions from the previous patches around expanding this to be a
> list of tools rather than just "AI" made sense, this is the example I
> gave in the cover letter:
>
> Assisted-by: Claude-claude-3-opus-20240229 checkpatch
>
> I find something like that useful because it tells me from the get-go
> that the submitter ran checkpatch on it (without having to spend a line
> in the commit message saying the same).
>
> I'm not sure about mixing human feedback into this, it might be
> difficult to interpert it later.
>
> It might work more naturally as an extension of Reviewed-by?
>
> Reviewed-by: Developer A <a@b.c> # Improved the XYZ algorithm
Maybe. Dunno.
Sometimes I just give style suggestions or notes for things I'm
cc'd on but I don't really review it as a "Reviewed-by:" tag
seems to imply a more formal process.
> > Oh, and maybe a checkpatch update like this?
[]
> > diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
[]
> > @@ -641,6 +641,7 @@ our $signature_tags = qr{(?xi:
> > Reviewed-by:|
> > Reported-by:|
> > Suggested-by:|
> > + Assisted-by:|
> > To:|
> > Cc:
> > )};
>
> Yup, makes sense! I'll start including checkpatch updates going forward.
If the AI/coding 'Assisted-by:' tag doesn't have an email address,
then checkpatch is going to complain anyway.
Something in checkpatch's
# Check signature styles
block starting around line 3040 or so will also need updating.
© 2016 - 2025 Red Hat, Inc.