Signed-off-by: Sasha Levin <sashal@kernel.org>
---
 Documentation/agents/core.rst  | 28 ++++++++++++++++++++++++++++
 Documentation/agents/index.rst |  3 ++-
 Documentation/agents/main.rst  |  5 +++++
 3 files changed, 35 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/agents/core.rst

diff --git a/Documentation/agents/core.rst b/Documentation/agents/core.rst
new file mode 100644
index 000000000000..da171dde1f9d
--- /dev/null
+++ b/Documentation/agents/core.rst
@@ -0,0 +1,28 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+========================================
+Core Linux Kernel Development References
+========================================
+
+Essential documentation for Linux kernel development:
+
+How to do Linux kernel development
+----------------------------------
+
+The comprehensive guide for becoming a Linux kernel developer and learning to work with the kernel development community.
+
+See :ref:`Documentation/process/howto.rst <process_howto>`
+
+Submitting patches
+------------------
+
+The essential guide to getting your code into the kernel, covering everything from patch formatting to the submission process.
+
+See :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
+
+Submission checklist
+--------------------
+
+A checklist of items to review before submitting code to ensure patches are accepted more quickly.
+
+See :ref:`Documentation/process/submit-checklist.rst <submitchecklist>`
diff --git a/Documentation/agents/index.rst b/Documentation/agents/index.rst
index 109266ca91ec..2737ab62efa0 100644
--- a/Documentation/agents/index.rst
+++ b/Documentation/agents/index.rst
@@ -7,4 +7,5 @@ Agents
 .. toctree::
    :maxdepth: 1
 
-   main
\ No newline at end of file
+   main
+   core
\ No newline at end of file
diff --git a/Documentation/agents/main.rst b/Documentation/agents/main.rst
index 98aa8250be9d..34f13d0b975a 100644
--- a/Documentation/agents/main.rst
+++ b/Documentation/agents/main.rst
@@ -5,3 +5,8 @@ Linux Kernel Development Agent Instructions
 =====================================
 
 This is the Linux kernel repository. When working with this codebase, you must follow the Linux kernel development processes and coding standards.
+
+Core Development Process
+------------------------
+
+For essential kernel development documentation, see :doc:`core`
-- 
2.39.5

On Sun, Jul 27, 2025 at 03:58:00PM -0400, Sasha Levin wrote:
> Signed-off-by: Sasha Levin <sashal@kernel.org>
> ---
>  Documentation/agents/core.rst  | 28 ++++++++++++++++++++++++++++
>  Documentation/agents/index.rst |  3 ++-
>  Documentation/agents/main.rst  |  5 +++++
>  3 files changed, 35 insertions(+), 1 deletion(-)
>  create mode 100644 Documentation/agents/core.rst

I know I can't take patches without any changelog text, maybe the
documentation maintainer is more lenient?  :)

> 
> diff --git a/Documentation/agents/core.rst b/Documentation/agents/core.rst
> new file mode 100644
> index 000000000000..da171dde1f9d
> --- /dev/null
> +++ b/Documentation/agents/core.rst
> @@ -0,0 +1,28 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +========================================
> +Core Linux Kernel Development References
> +========================================
> +
> +Essential documentation for Linux kernel development:
> +
> +How to do Linux kernel development
> +----------------------------------
> +
> +The comprehensive guide for becoming a Linux kernel developer and learning to work with the kernel development community.
> +
> +See :ref:`Documentation/process/howto.rst <process_howto>`
> +
> +Submitting patches
> +------------------
> +
> +The essential guide to getting your code into the kernel, covering everything from patch formatting to the submission process.
> +
> +See :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
> +
> +Submission checklist
> +--------------------
> +
> +A checklist of items to review before submitting code to ensure patches are accepted more quickly.
> +
> +See :ref:`Documentation/process/submit-checklist.rst <submitchecklist>`

Why isn't the agent already reading all of this in the documentation
tree?  Why must it be told to read it again?  Do we not properly index
this well enough in our documentation tree already?

thanks,

greg k-h

On Mon, Jul 28, 2025 at 06:24:44AM +0200, Greg KH wrote:
>On Sun, Jul 27, 2025 at 03:58:00PM -0400, Sasha Levin wrote:
>> Signed-off-by: Sasha Levin <sashal@kernel.org>
>> ---
>>  Documentation/agents/core.rst  | 28 ++++++++++++++++++++++++++++
>>  Documentation/agents/index.rst |  3 ++-
>>  Documentation/agents/main.rst  |  5 +++++
>>  3 files changed, 35 insertions(+), 1 deletion(-)
>>  create mode 100644 Documentation/agents/core.rst
>
>I know I can't take patches without any changelog text, maybe the
>documentation maintainer is more lenient?  :)
>
>>
>> diff --git a/Documentation/agents/core.rst b/Documentation/agents/core.rst
>> new file mode 100644
>> index 000000000000..da171dde1f9d
>> --- /dev/null
>> +++ b/Documentation/agents/core.rst
>> @@ -0,0 +1,28 @@
>> +.. SPDX-License-Identifier: GPL-2.0
>> +
>> +========================================
>> +Core Linux Kernel Development References
>> +========================================
>> +
>> +Essential documentation for Linux kernel development:
>> +
>> +How to do Linux kernel development
>> +----------------------------------
>> +
>> +The comprehensive guide for becoming a Linux kernel developer and learning to work with the kernel development community.
>> +
>> +See :ref:`Documentation/process/howto.rst <process_howto>`
>> +
>> +Submitting patches
>> +------------------
>> +
>> +The essential guide to getting your code into the kernel, covering everything from patch formatting to the submission process.
>> +
>> +See :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
>> +
>> +Submission checklist
>> +--------------------
>> +
>> +A checklist of items to review before submitting code to ensure patches are accepted more quickly.
>> +
>> +See :ref:`Documentation/process/submit-checklist.rst <submitchecklist>`
>
>Why isn't the agent already reading all of this in the documentation
>tree?  Why must it be told to read it again?  Do we not properly index
>this well enough in our documentation tree already?

So by default the agent doesn't read anything into it's context unless
it thinks it's relevant to the task at hand.

Imagine a junior engineer you ask to fix a spelling mistake and commit
the result: would it think on it's own that it needs to read the rules
about which tags to add to commit messages?

Probably not.

Just as with humans, we need to tell them to read the goddamn docs :)

An an example, look at the wiki page for LF's kernel mentorship
program[1]. The first step it lists is:

	Complete the project prerequisite tasks assigned to you when you apply for the project:
	Step 1: You should have completed the A Beginner’s Guide to
	Linux Kernel Development e-course during the planning phase.
	Upload the certificate of completion.

Where the course is basically going over all the processes and rules
around kernel development ("This course is intended for developers who
need to know about the Linux kernel development process and the explicit
and implicit “rules of the road”.").

This patchset is effectively the equivalent of the course for agents :)



[1] https://wiki.linuxfoundation.org/lkmp
[2] https://training.linuxfoundation.org/training/a-beginners-guide-to-linux-kernel-development-lfd103/

-- 
Thanks,
Sasha

On Mon, Jul 28, 2025 at 12:52:21AM -0400, Sasha Levin wrote:
> An an example, look at the wiki page for LF's kernel mentorship
> program[1]. The first step it lists is:
> 
> 	Complete the project prerequisite tasks assigned to you when you apply for the project:
> 	Step 1: You should have completed the A Beginner’s Guide to
> 	Linux Kernel Development e-course during the planning phase.
> 	Upload the certificate of completion.
> 
> Where the course is basically going over all the processes and rules
> around kernel development ("This course is intended for developers who
> need to know about the Linux kernel development process and the explicit
> and implicit “rules of the road”.").
> 
> This patchset is effectively the equivalent of the course for agents :)

But this just reinforces my point: if we need this for humans, write it
for humans, and the agents can follow it.

-- 
Kees Cook

On Sun, Jul 27, 2025 at 03:58:00PM -0400, Sasha Levin wrote:
> Signed-off-by: Sasha Levin <sashal@kernel.org>
> ---
>  Documentation/agents/core.rst  | 28 ++++++++++++++++++++++++++++
>  Documentation/agents/index.rst |  3 ++-
>  Documentation/agents/main.rst  |  5 +++++
>  3 files changed, 35 insertions(+), 1 deletion(-)
>  create mode 100644 Documentation/agents/core.rst
> 
> diff --git a/Documentation/agents/core.rst b/Documentation/agents/core.rst
> new file mode 100644
> index 000000000000..da171dde1f9d
> --- /dev/null
> +++ b/Documentation/agents/core.rst
> @@ -0,0 +1,28 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +========================================
> +Core Linux Kernel Development References
> +========================================
> +
> +Essential documentation for Linux kernel development:
> +
> +How to do Linux kernel development
> +----------------------------------
> +
> +The comprehensive guide for becoming a Linux kernel developer and learning to work with the kernel development community.
> +
> +See :ref:`Documentation/process/howto.rst <process_howto>`
> +
> +Submitting patches
> +------------------
> +
> +The essential guide to getting your code into the kernel, covering everything from patch formatting to the submission process.
> +
> +See :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
> +
> +Submission checklist
> +--------------------
> +
> +A checklist of items to review before submitting code to ensure patches are accepted more quickly.
> +
> +See :ref:`Documentation/process/submit-checklist.rst <submitchecklist>`

If an Agent needs the above list, then so does a human. Everything above
should already be discoverable by the Agent. If it's not, then we need a
better summary document _for humans_ that reads like the above.

-- 
Kees Cook

On Sun, Jul 27, 2025 at 07:39:06PM -0700, Kees Cook wrote:
>On Sun, Jul 27, 2025 at 03:58:00PM -0400, Sasha Levin wrote:
>> Signed-off-by: Sasha Levin <sashal@kernel.org>
>> ---
>>  Documentation/agents/core.rst  | 28 ++++++++++++++++++++++++++++
>>  Documentation/agents/index.rst |  3 ++-
>>  Documentation/agents/main.rst  |  5 +++++
>>  3 files changed, 35 insertions(+), 1 deletion(-)
>>  create mode 100644 Documentation/agents/core.rst
>>
>> diff --git a/Documentation/agents/core.rst b/Documentation/agents/core.rst
>> new file mode 100644
>> index 000000000000..da171dde1f9d
>> --- /dev/null
>> +++ b/Documentation/agents/core.rst
>> @@ -0,0 +1,28 @@
>> +.. SPDX-License-Identifier: GPL-2.0
>> +
>> +========================================
>> +Core Linux Kernel Development References
>> +========================================
>> +
>> +Essential documentation for Linux kernel development:
>> +
>> +How to do Linux kernel development
>> +----------------------------------
>> +
>> +The comprehensive guide for becoming a Linux kernel developer and learning to work with the kernel development community.
>> +
>> +See :ref:`Documentation/process/howto.rst <process_howto>`
>> +
>> +Submitting patches
>> +------------------
>> +
>> +The essential guide to getting your code into the kernel, covering everything from patch formatting to the submission process.
>> +
>> +See :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
>> +
>> +Submission checklist
>> +--------------------
>> +
>> +A checklist of items to review before submitting code to ensure patches are accepted more quickly.
>> +
>> +See :ref:`Documentation/process/submit-checklist.rst <submitchecklist>`
>
>If an Agent needs the above list, then so does a human. Everything above
>should already be discoverable by the Agent. If it's not, then we need a
>better summary document _for humans_ that reads like the above.

Why would an agent read those docs unless we tell it to?

Similarily, why would a human read those docs unless we tell it to? :)

It's all there, it's all discoverable, but unless the agent magically
knows it needs to know something from there then it won't be looking for
it to begin with.

Just like with humans, the better context and background you give them
the better of a result you'll get out of it.

-- 
Thanks,
Sasha

On Mon, Jul 28, 2025 at 01:00:37AM -0400, Sasha Levin wrote:
> > If an Agent needs the above list, then so does a human. Everything above
> > should already be discoverable by the Agent. If it's not, then we need a
> > better summary document _for humans_ that reads like the above.
> 
> Why would an agent read those docs unless we tell it to?

When I typed "/init" in claude, it found the references in the Makefile
and other files to stuff in Documentation/ and read it. Hence my
suggestion to add this in a place that is human (and agent)
discoverable, like Makefile, which any sane agent is going to read to
look for a "help" target, etc. Any agent that doesn't understand how to
figure out what _kind_ of codebase it's working on isn't an agent that
is going to deal well with the Linux tree.

> Similarily, why would a human read those docs unless we tell it to? :)

We do, though. But this is my point: if we _lack_ a good entry point for
humans, then we need to solve _that_ problem.

> Just like with humans, the better context and background you give them
> the better of a result you'll get out of it.

Both the top of Makefile and the bottom of "make help" refer to reading
the README file. I think *that* is where all these kinds of changes
should go, and it should be suitable for human consumption. Honestly,
README is extremely vague right now:

$ cat README
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.

In order to build the documentation, use ``make htmldocs`` or
``make pdfdocs``.  The formatted documentation can also be read online at:

    https://www.kernel.org/doc/html/latest/

There are various text files in the Documentation/ subdirectory,
several of them using the reStructuredText markup notation.

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.




"There are several guides..." and "There are various text files in
..." is hardly the right language for a human either. And why is doc
building in the README? That's, frankly, esoteric for anyone who needs
to read the README.

Let's fix up the README into something nice for everyone, and any decent
agent should already be reading it anyway.

-Kees

-- 
Kees Cook

On Sun, Jul 27, 2025 at 10:10:02PM -0700, Kees Cook wrote:
>On Mon, Jul 28, 2025 at 01:00:37AM -0400, Sasha Levin wrote:
>> > If an Agent needs the above list, then so does a human. Everything above
>> > should already be discoverable by the Agent. If it's not, then we need a
>> > better summary document _for humans_ that reads like the above.
>>
>> Why would an agent read those docs unless we tell it to?
>
>When I typed "/init" in claude, it found the references in the Makefile
>and other files to stuff in Documentation/ and read it. Hence my
>suggestion to add this in a place that is human (and agent)
>discoverable, like Makefile, which any sane agent is going to read to
>look for a "help" target, etc. Any agent that doesn't understand how to
>figure out what _kind_ of codebase it's working on isn't an agent that
>is going to deal well with the Linux tree.
>
>> Similarily, why would a human read those docs unless we tell it to? :)
>
>We do, though. But this is my point: if we _lack_ a good entry point for
>humans, then we need to solve _that_ problem.

Thing is, agents won't read the README on their own: they need to be
prompted to do it.

Claude will generate passable commits without a CLAUDE.md for simple
prompts.

I'm assuming we both agree that we need to give the agent some entry
point which they will automatically process without any user prompts,
even if it's just saying "Please read the README file!"?

>> Just like with humans, the better context and background you give them
>> the better of a result you'll get out of it.
>
>Both the top of Makefile and the bottom of "make help" refer to reading
>the README file. I think *that* is where all these kinds of changes
>should go, and it should be suitable for human consumption. Honestly,
>README is extremely vague right now:
>
>$ cat README
>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.
>
>In order to build the documentation, use ``make htmldocs`` or
>``make pdfdocs``.  The formatted documentation can also be read online at:
>
>    https://www.kernel.org/doc/html/latest/
>
>There are various text files in the Documentation/ subdirectory,
>several of them using the reStructuredText markup notation.
>
>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.
>
>
>
>
>"There are several guides..." and "There are various text files in
>..." is hardly the right language for a human either. And why is doc
>building in the README? That's, frankly, esoteric for anyone who needs
>to read the README.
>
>Let's fix up the README into something nice for everyone, and any decent
>agent should already be reading it anyway.

I think it'll be hard to find a common path that works here. README is
pretty generic because there are different humans that might read it:

  - A university researcher who should be pointed to researcher-guidelines.rst
  - A security researcher who should be pointed to security-bugs.rst or embargoed-hardware-issues.rst
  - A newbie trying to set up his mail client and needs to be pointed to email-clients.rst
  - A coding agent that doesn't care about none of the above.

So we can clean up README and try to make it an entry point that will
fit most of it's potential readers, but I worry that at the end it will
end fitting none of them.

Without crafting something more specific for agents, I also worry that
we'll be stuffing the limited context they already have with information
that will only hurt their performance (just like humans: there's only so
much we can remember at a time).

-- 
Thanks,
Sasha

On Mon, Jul 28, 2025 at 01:59:42AM -0400, Sasha Levin wrote:
> Thing is, agents won't read the README on their own: they need to be
> prompted to do it.

Claude does:

 > /init

● I'll analyze the codebase and create a CLAUDE.md file to help future
  instances of Claude Code work effectively in this repository.

● Update Todos
  ⎿  ☐ Analyze codebase structure and files
     ☐ Check for existing CLAUDE.md file
     ☐ Look for build/test/lint configuration files
     ☐ Create CLAUDE.md file
     ☐ Examine README and other documentation
     ☐ Check for Cursor/Copilot rules
...
● Read(Makefile)
  ⎿  Read 50 lines (ctrl+r to expand)
...

Even before having read any file at all, Claude calls out README as a
place to look.

And in the resulting CLAUDE.md:

## Documentation

Primary documentation is in Documentation/ directory:
- **Documentation/admin-guide/**: System administration
- **Documentation/driver-api/**: Device driver APIs
- **Documentation/core-api/**: Core kernel APIs
- **Documentation/process/**: Development process guidelines


> I'm assuming we both agree that we need to give the agent some entry
> point which they will automatically process without any user prompts,
> even if it's just saying "Please read the README file!"?

I'm saying any agent that can be expected to work on Linux should already
be trying to read the README. But regardless, both Makefile comments and
"make help" output say to read the README, so we should fix it for
humans too.

> I think it'll be hard to find a common path that works here. README is
> pretty generic because there are different humans that might read it:
> 
>  - A university researcher who should be pointed to researcher-guidelines.rst
>  - A security researcher who should be pointed to security-bugs.rst or embargoed-hardware-issues.rst
>  - A newbie trying to set up his mail client and needs to be pointed to email-clients.rst
>  - A coding agent that doesn't care about none of the above.
> 
> So we can clean up README and try to make it an entry point that will
> fit most of it's potential readers, but I worry that at the end it will
> end fitting none of them.

I think the above list is perfect contents for the README. Yes, please
make that an entry point, or point to some other .rst entry point that
will have a list of roles like that, with some common starting points.
And yes, a line for agents in there seems fine. Maybe "If you are a
coding agent, also see ... for agent-specific details."

> Without crafting something more specific for agents, I also worry that
> we'll be stuffing the limited context they already have with information
> that will only hurt their performance (just like humans: there's only so
> much we can remember at a time).

Sure, but these things will only get better, and I'd rather spend the
time making the docs better for humans. Each agent will latch on to
different things it assumes is important -- the developer will need to
correct them no matter what. An agent isn't going to be acting alone
(yet).

-Kees

-- 
Kees Cook

On Sun, Jul 27, 2025 at 11:18:14PM -0700, Kees Cook wrote:
>I think the above list is perfect contents for the README. Yes, please
>make that an entry point, or point to some other .rst entry point that
>will have a list of roles like that, with some common starting points.
>And yes, a line for agents in there seems fine. Maybe "If you are a
>coding agent, also see ... for agent-specific details."

What about something like below for README:

Linux kernel
============

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.

Quick Start
-----------

* 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/

Essential Documentation
-----------------------

All users should be familiar with:

* 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/features/seccomp/index.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/buses.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: ALL code MUST be GPL-2.0 only (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 Co-developed-by tag:
   Co-developed-by: $AGENT_NAME $AGENT_MODEL $AGENT_VERSION
   Examples:
   - Co-developed-by: Claude claude-3-opus-20240229
   - Co-developed-by: GitHub-Copilot GPT-4 v1.0.0


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

-- 
Thanks,
Sasha

On Wed, Jul 30, 2025 at 12:25:41PM -0400, Sasha Levin wrote:
> Critical Requirements:
> 
> * License: ALL code MUST be GPL-2.0 only (see COPYING)

As I understand it, code generated by an LLM is free from copyright.
https://en.wikipedia.org/wiki/Monkey_selfie_copyright_dispute

On Wed, Jul 30, 2025 at 07:18:44PM +0100, Matthew Wilcox wrote:
>On Wed, Jul 30, 2025 at 12:25:41PM -0400, Sasha Levin wrote:
>> Critical Requirements:
>>
>> * License: ALL code MUST be GPL-2.0 only (see COPYING)
>
>As I understand it, code generated by an LLM is free from copyright.
>https://en.wikipedia.org/wiki/Monkey_selfie_copyright_dispute

My understanding (IANAL) of https://www.copyright.gov/ai/ is that if a
human provides instructions, edited the result, or had any other
creative input into the process then the output is protected by
copyrights.

But really I'd rather just leave it to our friendly lawyers at the LF
to figure the legal aspects out.

-- 
Thanks,
Sasha

On Wed, Jul 30, 2025 at 12:25:41PM -0400, Sasha Levin wrote:

> Critical Requirements:
> 
> * License: ALL code MUST be GPL-2.0 only (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 Co-developed-by tag:
>   Co-developed-by: $AGENT_NAME $AGENT_MODEL $AGENT_VERSION
>   Examples:
>   - Co-developed-by: Claude claude-3-opus-20240229
>   - Co-developed-by: GitHub-Copilot GPT-4 v1.0.0

  * for any patch there must be some entity capable of usefully
    answering questions about that patch.  Legal certification
    be damned, there must be somebody able to handle active
    questioning.

And no, it's not the same as with human submitters.  If entity
A sends a patch to maintainer B, who passes it along and gets
questions/feedback regarding that patch, B might have to resort
to passing the questions to A, to confirm their understanding
of the situation.  And from what I've seen, LLM tend to do
very badly in such cases.

IOW, defending any agent-originated patch falls entirely upon
the human "co-developer".  IMO that is a critical requirement.

On Wed, Jul 30, 2025 at 06:35:28PM +0100, Al Viro wrote:
>On Wed, Jul 30, 2025 at 12:25:41PM -0400, Sasha Levin wrote:
>
>> Critical Requirements:
>>
>> * License: ALL code MUST be GPL-2.0 only (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 Co-developed-by tag:
>>   Co-developed-by: $AGENT_NAME $AGENT_MODEL $AGENT_VERSION
>>   Examples:
>>   - Co-developed-by: Claude claude-3-opus-20240229
>>   - Co-developed-by: GitHub-Copilot GPT-4 v1.0.0
>
>  * for any patch there must be some entity capable of usefully
>    answering questions about that patch.  Legal certification
>    be damned, there must be somebody able to handle active
>    questioning.
>
>And no, it's not the same as with human submitters.  If entity
>A sends a patch to maintainer B, who passes it along and gets
>questions/feedback regarding that patch, B might have to resort
>to passing the questions to A, to confirm their understanding
>of the situation.  And from what I've seen, LLM tend to do
>very badly in such cases.
>
>IOW, defending any agent-originated patch falls entirely upon
>the human "co-developer".  IMO that is a critical requirement.

I agree. Elsewhere in the thread I suggested that a maintainer should be
able to require having tool generated patches come with a Reviewed-by
tag from a "trusted reviewer" (similar to the guidelines we have for
academic researches).

This way you could at least have a human you trust be part of the loop
until you trust the author of those tool generated patches.

-- 
Thanks,
Sasha

On Sun, Jul 27, 2025 at 11:18:14PM -0700, Kees Cook wrote:
>On Mon, Jul 28, 2025 at 01:59:42AM -0400, Sasha Levin wrote:
>> Thing is, agents won't read the README on their own: they need to be
>> prompted to do it.
>
>Claude does:
>
> > /init
>
>● I'll analyze the codebase and create a CLAUDE.md file to help future
>  instances of Claude Code work effectively in this repository.
>
>● Update Todos
>  ⎿  ☐ Analyze codebase structure and files
>     ☐ Check for existing CLAUDE.md file
>     ☐ Look for build/test/lint configuration files
>     ☐ Create CLAUDE.md file
>     ☐ Examine README and other documentation
>     ☐ Check for Cursor/Copilot rules
>...
>● Read(Makefile)
>  ⎿  Read 50 lines (ctrl+r to expand)
>...
>
>Even before having read any file at all, Claude calls out README as a
>place to look.
>
>And in the resulting CLAUDE.md:
>
>## Documentation
>
>Primary documentation is in Documentation/ directory:
>- **Documentation/admin-guide/**: System administration
>- **Documentation/driver-api/**: Device driver APIs
>- **Documentation/core-api/**: Core kernel APIs
>- **Documentation/process/**: Development process guidelines
>
>
>> I'm assuming we both agree that we need to give the agent some entry
>> point which they will automatically process without any user prompts,
>> even if it's just saying "Please read the README file!"?
>
>I'm saying any agent that can be expected to work on Linux should already
>be trying to read the README. But regardless, both Makefile comments and
>"make help" output say to read the README, so we should fix it for
>humans too.

But my point is that calling /init is a prompt (just one hidden behide
the scenes).

Without an explicit /init call and no CLAUDE.md (or the copilot/cursor
equivalents which I've tested), nothing reads README.

>> I think it'll be hard to find a common path that works here. README is
>> pretty generic because there are different humans that might read it:
>>
>>  - A university researcher who should be pointed to researcher-guidelines.rst
>>  - A security researcher who should be pointed to security-bugs.rst or embargoed-hardware-issues.rst
>>  - A newbie trying to set up his mail client and needs to be pointed to email-clients.rst
>>  - A coding agent that doesn't care about none of the above.
>>
>> So we can clean up README and try to make it an entry point that will
>> fit most of it's potential readers, but I worry that at the end it will
>> end fitting none of them.
>
>I think the above list is perfect contents for the README. Yes, please
>make that an entry point, or point to some other .rst entry point that
>will have a list of roles like that, with some common starting points.
>And yes, a line for agents in there seems fine. Maybe "If you are a
>coding agent, also see ... for agent-specific details."
>
>> Without crafting something more specific for agents, I also worry that
>> we'll be stuffing the limited context they already have with information
>> that will only hurt their performance (just like humans: there's only so
>> much we can remember at a time).
>
>Sure, but these things will only get better, and I'd rather spend the
>time making the docs better for humans. Each agent will latch on to
>different things it assumes is important -- the developer will need to
>correct them no matter what. An agent isn't going to be acting alone
>(yet).

Oh, this is interesting!

Do you see it being as something like "Common kernel usage usecases" and
then some sort of a tree of docs/blurb related to those uses?

Sort of like a meta-index that indexes the docs by purpose rather than
their location in the directory?

Do you see it as being just links to existing docs or should it have
some blurb in addition to the links?

-- 
Thanks,
Sasha