* [PATCH] [v3] Documentation: Provide guidelines for tool-generated content
From: Dave Hansen @ 2025-11-14 18:35 UTC (permalink / raw)
To: dave
Cc: Dave Hansen, Shuah Khan, Kees Cook, Greg Kroah-Hartman,
Miguel Ojeda, NeilBrown, Lorenzo Stoakes, Dan Williams,
Theodore Ts'o, Sasha Levin, Jonathan Corbet, Vlastimil Babka,
workflows, ksummit
In the last few years, the capabilities of coding tools have exploded.
As those capabilities have expanded, contributors and maintainers have
more and more questions about how and when to apply those
capabilities.
Add new Documentation to guide contributors on how to best use kernel
development tools, new and old.
Note, though, there are fundamentally no new or unique rules in this
new document. It clarifies expectations that the kernel community has
had for many years. For example, researchers are already asked to
disclose the tools they use to find issues in
Documentation/process/researcher-guidelines.rst. This new document
just reiterates existing best practices for development tooling.
In short: Please show your work and make sure your contribution is
easy to review.
Signed-off-by: Dave Hansen <dave.hansen@linux.intel.com>
Reviewed-by: Shuah Khan <shuah@kernel.org>
Reviewed-by: Kees Cook <kees@kernel.org>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Reviewed-by: Miguel Ojeda <ojeda@kernel.org>
Cc: NeilBrown <neilb@ownmail.net>
Cc: Lorenzo Stoakes <lorenzo.stoakes@oracle.com>
Cc: Dan Williams <dan.j.williams@intel.com>
Cc: Theodore Ts'o <tytso@mit.edu>
Cc: Sasha Levin <sashal@kernel.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Vlastimil Babka <vbabka@suse.cz>
Cc: workflows@vger.kernel.org
Cc: ksummit@lists.linux.dev
--
There has been a ton of feedback since v2. Thanks everyone! I've
tried to respect all of the feedback, but some of it has been
contradictory and I haven't been able to incorporate everything.
Please speak up if I missed something important here.
Changes from v2:
* Mention testing (Shuah)
* Remove "very", rename LLM => coding assistant (Dan)
* More formatting sprucing up and minor typos (Miguel)
* Make changelog and text less flashy (Christian)
* Tone down critical=>helpful (Neil)
Changes from v1:
* Rename to generated-content.rst and add to documentation index.
(Jon)
* Rework subject to align with the new filename
* Replace commercial names with generic ones. (Jon)
* Be consistent about punctuation at the end of bullets for whole
sentences. (Miguel)
* Formatting sprucing up and minor typos (Miguel)
This document was a collaborative effort from all the members of
the TAB. I just reformatted it into .rst and wrote the changelog.
---
Documentation/process/generated-content.rst | 96 +++++++++++++++++++++
Documentation/process/index.rst | 1 +
2 files changed, 97 insertions(+)
create mode 100644 Documentation/process/generated-content.rst
diff --git a/Documentation/process/generated-content.rst b/Documentation/process/generated-content.rst
new file mode 100644
index 0000000000000..acdf23819d685
--- /dev/null
+++ b/Documentation/process/generated-content.rst
@@ -0,0 +1,96 @@
+============================================
+Kernel Guidelines for Tool Generated Content
+============================================
+
+Purpose
+=======
+
+Kernel contributors have been using tooling to generate contributions
+for a long time. These tools can increase the volume of contributions.
+At the same time, reviewer and maintainer bandwidth is a scarce
+resource. Understanding which portions of a contribution come from
+humans versus tools is helpful to maintain those resources and keep
+kernel development healthy.
+
+The goal here is to clarify community expectations around tools. This
+lets everyone become more productive while also maintaining high
+degrees of trust between submitters and reviewers.
+
+Out of Scope
+============
+
+These guidelines do not apply to tools that make trivial tweaks to
+preexisting content. Nor do they pertain to AI tooling that helps with
+menial tasks. Some examples:
+
+ - Spelling and grammar fix ups, like rephrasing to imperative voice
+ - Typing aids like identifier completion, common boilerplate or
+ trivial pattern completion
+ - Purely mechanical transformations like variable renaming
+ - Reformatting, like running Lindent, ``clang-format`` or
+ ``rust-fmt``
+
+Even if your tool use is out of scope you should still always consider
+if it would help reviewing your contribution if the reviewer knows
+about the tool that you used.
+
+In Scope
+========
+
+These guidelines apply when a meaningful amount of content in a kernel
+contribution was not written by a person in the Signed-off-by chain,
+but was instead created by a tool.
+
+Detection of a problem and testing the fix for it is also part of the
+development process; if a tool was used to find a problem addressed by
+a change, that should be noted in the changelog. This not only gives
+credit where it is due, it also helps fellow developers find out about
+these tools.
+
+Some examples:
+ - Any tool-suggested fix such as ``checkpatch.pl --fix``
+ - Coccinelle scripts
+ - A chatbot generated a new function in your patch to sort list entries.
+ - A .c file in the patch was originally generated by a coding
+ assistant but cleaned up by hand.
+ - The changelog was generated by handing the patch to a generative AI
+ tool and asking it to write the changelog.
+ - The changelog was translated from another language.
+
+If in doubt, choose transparency and assume these guidelines apply to
+your contribution.
+
+Guidelines
+==========
+
+First, read the Developer's Certificate of Origin:
+Documentation/process/submitting-patches.rst. Its rules are simple
+and have been in place for a long time. They have covered many
+tool-generated contributions. Ensure that you understand your entire
+submission and are prepared to respond to review comments.
+
+Second, when making a contribution, be transparent about the origin of
+content in cover letters and changelogs. You can be more transparent
+by adding information like this:
+
+ - What tools were used?
+ - The input to the tools you used, like the Coccinelle source script.
+ - If code was largely generated from a single or short set of
+ prompts, include those prompts. For longer sessions, include a
+ summary of the prompts and the nature of resulting assistance.
+ - Which portions of the content were affected by that tool?
+ - How is the submission tested and tools used to test the fix?
+
+As with all contributions, individual maintainers have discretion to
+choose how they handle the contribution. For example, they might:
+
+ - Treat it just like any other contribution.
+ - Reject it outright.
+ - Treat the contribution specially like reviewing with extra scrutiny,
+ or at a lower priority than human-generated content
+ - Suggest a better prompt instead of suggesting specific code changes.
+ - Ask for some other special steps, like asking the contributor to
+ elaborate on how the tool or model was trained.
+ - Ask the submitter to explain in more detail about the contribution
+ so that the maintainer can feel comfortable that the submitter fully
+ understands how the code works.
diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst
index aa12f26601949..e1a8a31389f53 100644
--- a/Documentation/process/index.rst
+++ b/Documentation/process/index.rst
@@ -68,6 +68,7 @@ beyond).
stable-kernel-rules
management-style
researcher-guidelines
+ generated-content
Dealing with bugs
-----------------
--
2.34.1
^ permalink raw reply related
* Re: [PATCH] [v3] Documentation: Provide guidelines for tool-generated content
From: Luis Chamberlain @ 2025-11-14 20:08 UTC (permalink / raw)
To: Dave Hansen, Julia Lawall, Linus Torvalds, Takashi Iwai
Cc: dave, Shuah Khan, Kees Cook, Greg Kroah-Hartman, Miguel Ojeda,
NeilBrown, Lorenzo Stoakes, Dan Williams, Theodore Ts'o,
Sasha Levin, Jonathan Corbet, Vlastimil Babka, workflows, ksummit
In-Reply-To: <20251114183528.1239900-1-dave.hansen@linux.intel.com>
On Fri, Nov 14, 2025 at 10:35:28AM -0800, Dave Hansen wrote:
> In the last few years, the capabilities of coding tools have exploded.
> As those capabilities have expanded, contributors and maintainers have
> more and more questions about how and when to apply those
> capabilities.
>
> Add new Documentation to guide contributors on how to best use kernel
> development tools, new and old.
>
> Note, though, there are fundamentally no new or unique rules in this
> new document. It clarifies expectations that the kernel community has
> had for many years. For example, researchers are already asked to
> disclose the tools they use to find issues in
> Documentation/process/researcher-guidelines.rst. This new document
> just reiterates existing best practices for development tooling.
>
> In short: Please show your work and make sure your contribution is
> easy to review.
>
> Signed-off-by: Dave Hansen <dave.hansen@linux.intel.com>
> Reviewed-by: Shuah Khan <shuah@kernel.org>
> Reviewed-by: Kees Cook <kees@kernel.org>
> Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> Reviewed-by: Miguel Ojeda <ojeda@kernel.org>
> Cc: NeilBrown <neilb@ownmail.net>
> Cc: Lorenzo Stoakes <lorenzo.stoakes@oracle.com>
> Cc: Dan Williams <dan.j.williams@intel.com>
> Cc: Theodore Ts'o <tytso@mit.edu>
> Cc: Sasha Levin <sashal@kernel.org>
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: Vlastimil Babka <vbabka@suse.cz>
> Cc: workflows@vger.kernel.org
> Cc: ksummit@lists.linux.dev
>
> --
>
> There has been a ton of feedback since v2. Thanks everyone! I've
> tried to respect all of the feedback, but some of it has been
> contradictory and I haven't been able to incorporate everything.
>
> Please speak up if I missed something important here.
>
> Changes from v2:
> * Mention testing (Shuah)
> * Remove "very", rename LLM => coding assistant (Dan)
> * More formatting sprucing up and minor typos (Miguel)
> * Make changelog and text less flashy (Christian)
> * Tone down critical=>helpful (Neil)
>
> Changes from v1:
> * Rename to generated-content.rst and add to documentation index.
> (Jon)
> * Rework subject to align with the new filename
> * Replace commercial names with generic ones. (Jon)
> * Be consistent about punctuation at the end of bullets for whole
> sentences. (Miguel)
> * Formatting sprucing up and minor typos (Miguel)
>
> This document was a collaborative effort from all the members of
> the TAB. I just reformatted it into .rst and wrote the changelog.
> ---
> Documentation/process/generated-content.rst | 96 +++++++++++++++++++++
> Documentation/process/index.rst | 1 +
> 2 files changed, 97 insertions(+)
> create mode 100644 Documentation/process/generated-content.rst
>
> diff --git a/Documentation/process/generated-content.rst b/Documentation/process/generated-content.rst
> new file mode 100644
> index 0000000000000..acdf23819d685
> --- /dev/null
> +++ b/Documentation/process/generated-content.rst
> @@ -0,0 +1,96 @@
> +============================================
> +Kernel Guidelines for Tool Generated Content
> +============================================
> +
> +Purpose
> +=======
> +
> +Kernel contributors have been using tooling to generate contributions
> +for a long time. These tools can increase the volume of contributions.
> +At the same time, reviewer and maintainer bandwidth is a scarce
> +resource. Understanding which portions of a contribution come from
> +humans versus tools is helpful to maintain those resources and keep
> +kernel development healthy.
> +
> +The goal here is to clarify community expectations around tools. This
> +lets everyone become more productive while also maintaining high
> +degrees of trust between submitters and reviewers.
> +
> +Out of Scope
> +============
> +
> +These guidelines do not apply to tools that make trivial tweaks to
> +preexisting content. Nor do they pertain to AI tooling that helps with
> +menial tasks. Some examples:
> +
> + - Spelling and grammar fix ups, like rephrasing to imperative voice
> + - Typing aids like identifier completion, common boilerplate or
> + trivial pattern completion
> + - Purely mechanical transformations like variable renaming
> + - Reformatting, like running Lindent, ``clang-format`` or
> + ``rust-fmt``
> +
> +Even if your tool use is out of scope you should still always consider
> +if it would help reviewing your contribution if the reviewer knows
> +about the tool that you used.
> +
> +In Scope
> +========
> +
> +These guidelines apply when a meaningful amount of content in a kernel
> +contribution was not written by a person in the Signed-off-by chain,
> +but was instead created by a tool.
> +
> +Detection of a problem and testing the fix for it is also part of the
> +development process; if a tool was used to find a problem addressed by
> +a change, that should be noted in the changelog. This not only gives
> +credit where it is due, it also helps fellow developers find out about
> +these tools.
> +
> +Some examples:
> + - Any tool-suggested fix such as ``checkpatch.pl --fix``
> + - Coccinelle scripts
> + - A chatbot generated a new function in your patch to sort list entries.
> + - A .c file in the patch was originally generated by a coding
> + assistant but cleaned up by hand.
> + - The changelog was generated by handing the patch to a generative AI
> + tool and asking it to write the changelog.
> + - The changelog was translated from another language.
> +
> +If in doubt, choose transparency and assume these guidelines apply to
> +your contribution.
> +
> +Guidelines
> +==========
> +
> +First, read the Developer's Certificate of Origin:
> +Documentation/process/submitting-patches.rst. Its rules are simple
> +and have been in place for a long time. They have covered many
> +tool-generated contributions. Ensure that you understand your entire
> +submission and are prepared to respond to review comments.
> +
> +Second, when making a contribution, be transparent about the origin of
> +content in cover letters and changelogs. You can be more transparent
> +by adding information like this:
> +
> + - What tools were used?
I really think we should just recommend the user to *consider* using:
Generated-by
I've been using it for Coccinelle on Linux for years, and it was not
just me. In other projects, in particular kdevops we started using this
to also be clear about the use of AI tools, and I've found it
instrumental to keep track of how much code *does not use it*.
> + - The input to the tools you used, like the Coccinelle source script.
> + - If code was largely generated from a single or short set of
> + prompts, include those prompts.
A long time ago we evaluated the question of using git notes for
coccinelle used input, and the issue back then was we didn't have support
for it I think. But I think that hump is gone?
If so, would using git notes for prompts be useful in this case as we scale
tooling outside of Coccinelle, like AI prompts? I believe this can be
instrumental for enhancing LLMs as well for fine tuned LLMs for Linux
development.
Otherwise, looks good.
Reviewed-by: Luis Chamberlain <mcgrof@kernel.org>
Luis
^ permalink raw reply
* Re: [PATCH] [v3] Documentation: Provide guidelines for tool-generated content
From: SeongJae Park @ 2025-11-14 20:17 UTC (permalink / raw)
To: Dave Hansen
Cc: SeongJae Park, dave, Shuah Khan, Kees Cook, Greg Kroah-Hartman,
Miguel Ojeda, NeilBrown, Lorenzo Stoakes, Dan Williams,
Theodore Ts'o, Sasha Levin, Jonathan Corbet, Vlastimil Babka,
workflows, ksummit
In-Reply-To: <20251114183528.1239900-1-dave.hansen@linux.intel.com>
On Fri, 14 Nov 2025 10:35:28 -0800 Dave Hansen <dave.hansen@linux.intel.com> wrote:
> In the last few years, the capabilities of coding tools have exploded.
> As those capabilities have expanded, contributors and maintainers have
> more and more questions about how and when to apply those
> capabilities.
>
> Add new Documentation to guide contributors on how to best use kernel
> development tools, new and old.
Thank you for writing this!
[...]
> +As with all contributions, individual maintainers have discretion to
> +choose how they handle the contribution. For example, they might:
> +
> + - Treat it just like any other contribution.
> + - Reject it outright.
> + - Treat the contribution specially like reviewing with extra scrutiny,
> + or at a lower priority than human-generated content
Nit. The ending period is missed?
Reviewed-by: SeongJae Park <sj@kernel.org>
Thanks,
SJ
[...]
Sent using hkml (https://github.com/sjp38/hackermail)
^ permalink raw reply
* Re: [PATCH] [v3] Documentation: Provide guidelines for tool-generated content
From: Dave Hansen @ 2025-11-14 22:52 UTC (permalink / raw)
To: Luis Chamberlain, Dave Hansen, Julia Lawall, Linus Torvalds,
Takashi Iwai
Cc: dave, Shuah Khan, Kees Cook, Greg Kroah-Hartman, Miguel Ojeda,
NeilBrown, Lorenzo Stoakes, Dan Williams, Theodore Ts'o,
Sasha Levin, Jonathan Corbet, Vlastimil Babka, workflows, ksummit
In-Reply-To: <aReMPda2sowBpkO-@bombadil.infradead.org>
On 11/14/25 12:08, Luis Chamberlain wrote:
...>> + - What tools were used?
>
> I really think we should just recommend the user to *consider* using:
>
> Generated-by
>
> I've been using it for Coccinelle on Linux for years, and it was not
> just me. In other projects, in particular kdevops we started using this
> to also be clear about the use of AI tools, and I've found it
> instrumental to keep track of how much code *does not use it*.
That sounds like a reasonable enough idea. But I think it's mostly
orthogonal to this document. If there were Generated-by documentation in
submitting-patches.rst, it would definitely get a special mention here.
>> + - The input to the tools you used, like the Coccinelle source script.
>> + - If code was largely generated from a single or short set of
>> + prompts, include those prompts.
>
> A long time ago we evaluated the question of using git notes for
> coccinelle used input, and the issue back then was we didn't have support
> for it I think. But I think that hump is gone?
>
> If so, would using git notes for prompts be useful in this case as we scale
> tooling outside of Coccinelle, like AI prompts? I believe this can be
> instrumental for enhancing LLMs as well for fine tuned LLMs for Linux
> development.
I looked at git notes a bit during the Link: tag discussion. There still
seem to be a few humps left, like git needing special configuration not
to lose notes on "git commit --amend" or rebases.
They seem to be _getting_ there, but they certainly don't seem to be a
nice, seamless thing that can easily be put into everyone's existing
workflows.
> Reviewed-by: Luis Chamberlain <mcgrof@kernel.org>
Thanks!
^ permalink raw reply
* Re: [PATCH] [v3] Documentation: Provide guidelines for tool-generated content
From: Dave Hansen @ 2025-11-14 22:53 UTC (permalink / raw)
To: SeongJae Park, Dave Hansen
Cc: dave, Shuah Khan, Kees Cook, Greg Kroah-Hartman, Miguel Ojeda,
NeilBrown, Lorenzo Stoakes, Dan Williams, Theodore Ts'o,
Sasha Levin, Jonathan Corbet, Vlastimil Babka, workflows, ksummit
In-Reply-To: <20251114201738.3212-1-sj@kernel.org>
On 11/14/25 12:17, SeongJae Park wrote:
>> + - Treat the contribution specially like reviewing with extra scrutiny,
>> + or at a lower priority than human-generated content
> Nit. The ending period is missed?
Fixed, thanks!
^ permalink raw reply
* Re: [PATCH] [v3] Documentation: Provide guidelines for tool-generated content
From: dan.j.williams @ 2025-11-14 23:19 UTC (permalink / raw)
To: Dave Hansen, dave
Cc: Dave Hansen, Shuah Khan, Kees Cook, Greg Kroah-Hartman,
Miguel Ojeda, NeilBrown, Lorenzo Stoakes, Dan Williams,
Theodore Ts'o, Sasha Levin, Jonathan Corbet, Vlastimil Babka,
workflows, ksummit
In-Reply-To: <20251114183528.1239900-1-dave.hansen@linux.intel.com>
Dave Hansen wrote:
> In the last few years, the capabilities of coding tools have exploded.
> As those capabilities have expanded, contributors and maintainers have
> more and more questions about how and when to apply those
> capabilities.
>
> Add new Documentation to guide contributors on how to best use kernel
> development tools, new and old.
>
> Note, though, there are fundamentally no new or unique rules in this
> new document. It clarifies expectations that the kernel community has
> had for many years. For example, researchers are already asked to
> disclose the tools they use to find issues in
> Documentation/process/researcher-guidelines.rst. This new document
> just reiterates existing best practices for development tooling.
>
> In short: Please show your work and make sure your contribution is
> easy to review.
>
> Signed-off-by: Dave Hansen <dave.hansen@linux.intel.com>
> Reviewed-by: Shuah Khan <shuah@kernel.org>
> Reviewed-by: Kees Cook <kees@kernel.org>
> Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> Reviewed-by: Miguel Ojeda <ojeda@kernel.org>
> Cc: NeilBrown <neilb@ownmail.net>
> Cc: Lorenzo Stoakes <lorenzo.stoakes@oracle.com>
> Cc: Dan Williams <dan.j.williams@intel.com>
All my concerns have been addressed.
Reviewed-by: Dan Williams <dan.j.williams@intel.com>
^ permalink raw reply
* Re: [PATCH] [v3] Documentation: Provide guidelines for tool-generated content
From: Thomas Gleixner @ 2025-11-15 15:22 UTC (permalink / raw)
To: Dave Hansen, dave
Cc: Dave Hansen, Shuah Khan, Kees Cook, Greg Kroah-Hartman,
Miguel Ojeda, NeilBrown, Lorenzo Stoakes, Dan Williams,
Theodore Ts'o, Sasha Levin, Jonathan Corbet, Vlastimil Babka,
workflows, ksummit
In-Reply-To: <20251114183528.1239900-1-dave.hansen@linux.intel.com>
On Fri, Nov 14 2025 at 10:35, Dave Hansen wrote:
> +In Scope
> +========
> +
> +These guidelines apply when a meaningful amount of content in a kernel
> +contribution was not written by a person in the Signed-off-by chain,
> +but was instead created by a tool.
> +
> +Detection of a problem and testing the fix for it is also part of the
> +development process; if a tool was used to find a problem addressed by
> +a change, that should be noted in the changelog. This not only gives
> +credit where it is due, it also helps fellow developers find out about
> +these tools.
> +
> +Some examples:
> + - Any tool-suggested fix such as ``checkpatch.pl --fix``
> + - Coccinelle scripts
> + - A chatbot generated a new function in your patch to sort list entries.
> + - A .c file in the patch was originally generated by a coding
> + assistant but cleaned up by hand.
> + - The changelog was generated by handing the patch to a generative AI
> + tool and asking it to write the changelog.
> + - The changelog was translated from another language.
> +
> +If in doubt, choose transparency and assume these guidelines apply to
> +your contribution.
Can we pretty please define a tag and format for this?
I'm not really interested in the creative ways which will otherwise make
change logs even more incomprehensible.
Thanks
tglx
^ permalink raw reply
* Re: [PATCH] [v3] Documentation: Provide guidelines for tool-generated content
From: Steven Rostedt @ 2025-11-15 19:02 UTC (permalink / raw)
To: Dave Hansen
Cc: dave, Shuah Khan, Kees Cook, Greg Kroah-Hartman, Miguel Ojeda,
NeilBrown, Lorenzo Stoakes, Dan Williams, Theodore Ts'o,
Sasha Levin, Jonathan Corbet, Vlastimil Babka, workflows, ksummit
In-Reply-To: <20251114183528.1239900-1-dave.hansen@linux.intel.com>
On Fri, 14 Nov 2025 10:35:28 -0800
Dave Hansen <dave.hansen@linux.intel.com> wrote:
> In the last few years, the capabilities of coding tools have exploded.
> As those capabilities have expanded, contributors and maintainers have
> more and more questions about how and when to apply those
> capabilities.
>
> Add new Documentation to guide contributors on how to best use kernel
> development tools, new and old.
>
> Note, though, there are fundamentally no new or unique rules in this
> new document. It clarifies expectations that the kernel community has
> had for many years. For example, researchers are already asked to
> disclose the tools they use to find issues in
> Documentation/process/researcher-guidelines.rst. This new document
> just reiterates existing best practices for development tooling.
>
> In short: Please show your work and make sure your contribution is
> easy to review.
Thanks Dave for pushing this through!
Reviewed-by: Steven Rostedt <rostedt@goodmis.org>
-- Steve
>
> Signed-off-by: Dave Hansen <dave.hansen@linux.intel.com>
> Reviewed-by: Shuah Khan <shuah@kernel.org>
> Reviewed-by: Kees Cook <kees@kernel.org>
> Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> Reviewed-by: Miguel Ojeda <ojeda@kernel.org>
> Cc: NeilBrown <neilb@ownmail.net>
> Cc: Lorenzo Stoakes <lorenzo.stoakes@oracle.com>
> Cc: Dan Williams <dan.j.williams@intel.com>
> Cc: Theodore Ts'o <tytso@mit.edu>
> Cc: Sasha Levin <sashal@kernel.org>
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: Vlastimil Babka <vbabka@suse.cz>
> Cc: workflows@vger.kernel.org
> Cc: ksummit@lists.linux.dev
^ permalink raw reply
* Re: [PATCH] [v3] Documentation: Provide guidelines for tool-generated content
From: Steven Rostedt @ 2025-11-15 19:05 UTC (permalink / raw)
To: Thomas Gleixner
Cc: Dave Hansen, dave, Shuah Khan, Kees Cook, Greg Kroah-Hartman,
Miguel Ojeda, NeilBrown, Lorenzo Stoakes, Dan Williams,
Theodore Ts'o, Sasha Levin, Jonathan Corbet, Vlastimil Babka,
workflows, ksummit
In-Reply-To: <87qztz9v88.ffs@tglx>
On Sat, 15 Nov 2025 16:22:15 +0100
Thomas Gleixner <tglx@linutronix.de> wrote:
> > +If in doubt, choose transparency and assume these guidelines apply to
> > +your contribution.
>
> Can we pretty please define a tag and format for this?
>
> I'm not really interested in the creative ways which will otherwise make
> change logs even more incomprehensible.
As Dave responded to Luis, although that is a good idea, it's out of
scope for this document (for now). A patch that adds a tag to
submitting-patches can then update this document to mention it. But
until submitting-patches specifies what tag to use, we didn't want to
mention it in this document.
-- Steve
^ permalink raw reply
* Re: [PATCH] [v3] Documentation: Provide guidelines for tool-generated content
From: Steven Rostedt @ 2025-11-15 19:07 UTC (permalink / raw)
To: Thomas Gleixner
Cc: Dave Hansen, dave, Shuah Khan, Kees Cook, Greg Kroah-Hartman,
Miguel Ojeda, NeilBrown, Lorenzo Stoakes, Dan Williams,
Theodore Ts'o, Sasha Levin, Jonathan Corbet, Vlastimil Babka,
workflows, ksummit
In-Reply-To: <20251115140556.44aac254@batman.local.home>
On Sat, 15 Nov 2025 14:05:56 -0500
Steven Rostedt <rostedt@goodmis.org> wrote:
> As Dave responded to Luis, although that is a good idea, it's out of
> scope for this document (for now).
I should have said it's out of scope for this patch, not document. The
point is that what tag to use for this is a separate discussion.
-- Steve
^ permalink raw reply
* Re: [PATCH] [v3] Documentation: Provide guidelines for tool-generated content
From: Randy Dunlap @ 2025-11-15 20:10 UTC (permalink / raw)
To: Dave Hansen, dave
Cc: Shuah Khan, Kees Cook, Greg Kroah-Hartman, Miguel Ojeda,
NeilBrown, Lorenzo Stoakes, Dan Williams, Theodore Ts'o,
Sasha Levin, Jonathan Corbet, Vlastimil Babka, workflows, ksummit
In-Reply-To: <20251114183528.1239900-1-dave.hansen@linux.intel.com>
On 11/14/25 10:35 AM, Dave Hansen wrote:
> In the last few years, the capabilities of coding tools have exploded.
> As those capabilities have expanded, contributors and maintainers have
> more and more questions about how and when to apply those
> capabilities.
>
> Add new Documentation to guide contributors on how to best use kernel
> development tools, new and old.
>
> Note, though, there are fundamentally no new or unique rules in this
> new document. It clarifies expectations that the kernel community has
> had for many years. For example, researchers are already asked to
> disclose the tools they use to find issues in
"in" is ambiguous here. s/in/by/ or move the "in..." phrase to just
after "are already asked." Or maybe it doesn't matter in the commit
message. :)
> Documentation/process/researcher-guidelines.rst. This new document
> just reiterates existing best practices for development tooling.
>
> In short: Please show your work and make sure your contribution is
> easy to review.
>
> Signed-off-by: Dave Hansen <dave.hansen@linux.intel.com>
> Reviewed-by: Shuah Khan <shuah@kernel.org>
> Reviewed-by: Kees Cook <kees@kernel.org>
> Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> Reviewed-by: Miguel Ojeda <ojeda@kernel.org>
> Cc: NeilBrown <neilb@ownmail.net>
> Cc: Lorenzo Stoakes <lorenzo.stoakes@oracle.com>
> Cc: Dan Williams <dan.j.williams@intel.com>
> Cc: Theodore Ts'o <tytso@mit.edu>
> Cc: Sasha Levin <sashal@kernel.org>
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: Vlastimil Babka <vbabka@suse.cz>
> Cc: workflows@vger.kernel.org
> Cc: ksummit@lists.linux.dev
>
> --
>
> There has been a ton of feedback since v2. Thanks everyone! I've
> tried to respect all of the feedback, but some of it has been
> contradictory and I haven't been able to incorporate everything.
>
> Please speak up if I missed something important here.
>
> Changes from v2:
> * Mention testing (Shuah)
> * Remove "very", rename LLM => coding assistant (Dan)
> * More formatting sprucing up and minor typos (Miguel)
> * Make changelog and text less flashy (Christian)
> * Tone down critical=>helpful (Neil)
>
> Changes from v1:
> * Rename to generated-content.rst and add to documentation index.
> (Jon)
> * Rework subject to align with the new filename
> * Replace commercial names with generic ones. (Jon)
> * Be consistent about punctuation at the end of bullets for whole
> sentences. (Miguel)
> * Formatting sprucing up and minor typos (Miguel)
>
> This document was a collaborative effort from all the members of
> the TAB. I just reformatted it into .rst and wrote the changelog.
> ---
> Documentation/process/generated-content.rst | 96 +++++++++++++++++++++
> Documentation/process/index.rst | 1 +
> 2 files changed, 97 insertions(+)
> create mode 100644 Documentation/process/generated-content.rst
>
> diff --git a/Documentation/process/generated-content.rst b/Documentation/process/generated-content.rst
> new file mode 100644
> index 0000000000000..acdf23819d685
> --- /dev/null
> +++ b/Documentation/process/generated-content.rst
> @@ -0,0 +1,96 @@
> +============================================
> +Kernel Guidelines for Tool Generated Content
Tool-Generated
> +============================================
> +
> +Purpose
> +=======
> +
> +Kernel contributors have been using tooling to generate contributions
> +for a long time. These tools can increase the volume of contributions.
> +At the same time, reviewer and maintainer bandwidth is a scarce
> +resource. Understanding which portions of a contribution come from
> +humans versus tools is helpful to maintain those resources and keep
> +kernel development healthy.
> +
> +The goal here is to clarify community expectations around tools. This
> +lets everyone become more productive while also maintaining high
> +degrees of trust between submitters and reviewers.
> +
> +Out of Scope
> +============
> +
> +These guidelines do not apply to tools that make trivial tweaks to
> +preexisting content. Nor do they pertain to AI tooling that helps with
> +menial tasks. Some examples:
> +
> + - Spelling and grammar fix ups, like rephrasing to imperative voice
> + - Typing aids like identifier completion, common boilerplate or
> + trivial pattern completion
> + - Purely mechanical transformations like variable renaming
> + - Reformatting, like running Lindent, ``clang-format`` or
> + ``rust-fmt``
> +
> +Even if your tool use is out of scope you should still always consider
maybe: scope,
> +if it would help reviewing your contribution if the reviewer knows
> +about the tool that you used.
> +
> +In Scope
> +========
> +
> +These guidelines apply when a meaningful amount of content in a kernel
> +contribution was not written by a person in the Signed-off-by chain,
> +but was instead created by a tool.
> +
> +Detection of a problem and testing the fix for it is also part of the
> +development process; if a tool was used to find a problem addressed by
> +a change, that should be noted in the changelog. This not only gives
> +credit where it is due, it also helps fellow developers find out about
> +these tools.
> +
> +Some examples:
> + - Any tool-suggested fix such as ``checkpatch.pl --fix``
> + - Coccinelle scripts
> + - A chatbot generated a new function in your patch to sort list entries.
> + - A .c file in the patch was originally generated by a coding
> + assistant but cleaned up by hand.
> + - The changelog was generated by handing the patch to a generative AI
> + tool and asking it to write the changelog.
> + - The changelog was translated from another language.
> +
> +If in doubt, choose transparency and assume these guidelines apply to
> +your contribution.
> +
> +Guidelines
> +==========
> +
> +First, read the Developer's Certificate of Origin:
> +Documentation/process/submitting-patches.rst. Its rules are simple
> +and have been in place for a long time. They have covered many
> +tool-generated contributions. Ensure that you understand your entire
> +submission and are prepared to respond to review comments.
> +
> +Second, when making a contribution, be transparent about the origin of
> +content in cover letters and changelogs. You can be more transparent
> +by adding information like this:
> +
> + - What tools were used?
> + - The input to the tools you used, like the Coccinelle source script.
> + - If code was largely generated from a single or short set of
> + prompts, include those prompts. For longer sessions, include a
> + summary of the prompts and the nature of resulting assistance.
> + - Which portions of the content were affected by that tool?
> + - How is the submission tested and tools used to test the fix?
and what tools were used to test the fix?
> +
> +As with all contributions, individual maintainers have discretion to
> +choose how they handle the contribution. For example, they might:
> +
> + - Treat it just like any other contribution.
> + - Reject it outright.
> + - Treat the contribution specially like reviewing with extra scrutiny,
> + or at a lower priority than human-generated content
> + - Suggest a better prompt instead of suggesting specific code changes.
> + - Ask for some other special steps, like asking the contributor to
> + elaborate on how the tool or model was trained.
> + - Ask the submitter to explain in more detail about the contribution
> + so that the maintainer can feel comfortable that the submitter fully
> + understands how the code works.
thanks.
--
~Randy
^ permalink raw reply
* Re: [PATCH] [v3] Documentation: Provide guidelines for tool-generated content
From: Thomas Gleixner @ 2025-11-15 23:30 UTC (permalink / raw)
To: Steven Rostedt
Cc: Dave Hansen, dave, Shuah Khan, Kees Cook, Greg Kroah-Hartman,
Miguel Ojeda, NeilBrown, Lorenzo Stoakes, Dan Williams,
Theodore Ts'o, Sasha Levin, Jonathan Corbet, Vlastimil Babka,
workflows, ksummit
In-Reply-To: <20251115140746.6a3acfd5@batman.local.home>
On Sat, Nov 15 2025 at 14:07, Steven Rostedt wrote:
> On Sat, 15 Nov 2025 14:05:56 -0500
> Steven Rostedt <rostedt@goodmis.org> wrote:
>
>> As Dave responded to Luis, although that is a good idea, it's out of
>> scope for this document (for now).
>
> I should have said it's out of scope for this patch, not document. The
> point is that what tag to use for this is a separate discussion.
Which should be held in the context of this patch to make it complete.
Thanks,
tglx
^ permalink raw reply
* Re: [PATCH] [v3] Documentation: Provide guidelines for tool-generated content
From: Rafael J. Wysocki @ 2025-11-16 12:38 UTC (permalink / raw)
To: Steven Rostedt, Thomas Gleixner
Cc: Dave Hansen, dave, Shuah Khan, Kees Cook, Greg Kroah-Hartman,
Miguel Ojeda, NeilBrown, Lorenzo Stoakes, Dan Williams,
Theodore Ts'o, Sasha Levin, Jonathan Corbet, Vlastimil Babka,
workflows, ksummit
In-Reply-To: <877bvqan70.ffs@tglx>
On Sunday, November 16, 2025 12:30:27 AM CET Thomas Gleixner wrote:
> On Sat, Nov 15 2025 at 14:07, Steven Rostedt wrote:
> > On Sat, 15 Nov 2025 14:05:56 -0500
> > Steven Rostedt <rostedt@goodmis.org> wrote:
> >
> >> As Dave responded to Luis, although that is a good idea, it's out of
> >> scope for this document (for now).
> >
> > I should have said it's out of scope for this patch, not document. The
> > point is that what tag to use for this is a separate discussion.
>
> Which should be held in the context of this patch to make it complete.
I agree, it would be good to get it all done in one go.
^ permalink raw reply
* Re: [PATCH] [v3] Documentation: Provide guidelines for tool-generated content
From: Kees Cook @ 2025-11-16 15:25 UTC (permalink / raw)
To: Rafael J. Wysocki, Steven Rostedt, Thomas Gleixner
Cc: Dave Hansen, dave, Shuah Khan, Greg Kroah-Hartman, Miguel Ojeda,
NeilBrown, Lorenzo Stoakes, Dan Williams, Theodore Ts'o,
Sasha Levin, Jonathan Corbet, Vlastimil Babka, workflows, ksummit
In-Reply-To: <2804290.mvXUDI8C0e@rafael.j.wysocki>
On November 16, 2025 4:38:35 AM PST, "Rafael J. Wysocki" <rafael@kernel.org> wrote:
>On Sunday, November 16, 2025 12:30:27 AM CET Thomas Gleixner wrote:
>> On Sat, Nov 15 2025 at 14:07, Steven Rostedt wrote:
>> > On Sat, 15 Nov 2025 14:05:56 -0500
>> > Steven Rostedt <rostedt@goodmis.org> wrote:
>> >
>> >> As Dave responded to Luis, although that is a good idea, it's out of
>> >> scope for this document (for now).
>> >
>> > I should have said it's out of scope for this patch, not document. The
>> > point is that what tag to use for this is a separate discussion.
>>
>> Which should be held in the context of this patch to make it complete.
>
>I agree, it would be good to get it all done in one go.
A tag isn't going to capture what we need today. Because the LLM usage is so variable, it'll be, at best, misleading or, at worst, totally inaccurate. I've provided several examples of this where the range of LLM involvement is very low to very high. The prior discussions have shown that we haven't yet found a sensible way for a tag to capture that.
But the common thing everyone appears to agree on is the "show your work" concept that this patch is trying to capture. I think it's likely we'll grow a tag eventually, but it isn't something we understand the context for yet. As a first step, this document is designed to show the foundational goals for what we want documented.
Over some time of applying this, we'll start to see common patterns and repeated descriptions in commit logs. At that point, I think a tag will be warranted. But right now, we don't generally agree about what aspects we want a tag to cover.
-Kees
--
Kees Cook
^ permalink raw reply
* Re: [PATCH] [v3] Documentation: Provide guidelines for tool-generated content
From: Steven Rostedt @ 2025-11-16 16:01 UTC (permalink / raw)
To: Rafael J. Wysocki
Cc: Thomas Gleixner, Dave Hansen, dave, Shuah Khan, Kees Cook,
Greg Kroah-Hartman, Miguel Ojeda, NeilBrown, Lorenzo Stoakes,
Dan Williams, Theodore Ts'o, Sasha Levin, Jonathan Corbet,
Vlastimil Babka, workflows, ksummit
In-Reply-To: <2804290.mvXUDI8C0e@rafael.j.wysocki>
On Sun, 16 Nov 2025 13:38:35 +0100
"Rafael J. Wysocki" <rafael@kernel.org> wrote:
> On Sunday, November 16, 2025 12:30:27 AM CET Thomas Gleixner wrote:
> > On Sat, Nov 15 2025 at 14:07, Steven Rostedt wrote:
> > > On Sat, 15 Nov 2025 14:05:56 -0500
> > > Steven Rostedt <rostedt@goodmis.org> wrote:
> > >
> > >> As Dave responded to Luis, although that is a good idea, it's out of
> > >> scope for this document (for now).
> > >
> > > I should have said it's out of scope for this patch, not document. The
> > > point is that what tag to use for this is a separate discussion.
> >
> > Which should be held in the context of this patch to make it complete.
>
> I agree, it would be good to get it all done in one go.
>
>
It's still out of scope of this patch. As the change log states:
Note, though, there are fundamentally no new or unique rules in this
new document. It clarifies expectations that the kernel community has
had for many years.
A tag is a new rule. This document is to express existing behavior.
Adding a tag that currently doesn't match existing behavior should be a
separate patch.
-- Steve
^ permalink raw reply
* Re: [PATCH] [v3] Documentation: Provide guidelines for tool-generated content
From: Steven Rostedt @ 2025-11-16 16:17 UTC (permalink / raw)
To: Kees Cook
Cc: Rafael J. Wysocki, Thomas Gleixner, Dave Hansen, dave, Shuah Khan,
Greg Kroah-Hartman, Miguel Ojeda, NeilBrown, Lorenzo Stoakes,
Dan Williams, Theodore Ts'o, Sasha Levin, Jonathan Corbet,
Vlastimil Babka, workflows, ksummit
In-Reply-To: <EEF974E1-08D5-4E67-8AC4-4315CF9D10C1@kernel.org>
On Sun, 16 Nov 2025 07:25:46 -0800
Kees Cook <kees@kernel.org> wrote:
> A tag isn't going to capture what we need today. Because the LLM
> usage is so variable, it'll be, at best, misleading or, at worst,
> totally inaccurate. I've provided several examples of this where the
> range of LLM involvement is very low to very high. The prior
> discussions have shown that we haven't yet found a sensible way for a
> tag to capture that.
>
> But the common thing everyone appears to agree on is the "show your
> work" concept that this patch is trying to capture. I think it's
> likely we'll grow a tag eventually, but it isn't something we
> understand the context for yet. As a first step, this document is
> designed to show the foundational goals for what we want documented.
>
> Over some time of applying this, we'll start to see common patterns
> and repeated descriptions in commit logs. At that point, I think a
> tag will be warranted. But right now, we don't generally agree about
> what aspects we want a tag to cover.
Exactly. My fear was that by adding any new rules (like a tag) will
steer this conversation into a never ending bikeshed arguments, which
was exactly what we wanted to avoid.
Let's have the "tag" conversation at Maintainers Summit and just keep
this document as something to describe what we do today.
-- Steve
^ permalink raw reply
* [PATCH RESEND v4] checkpatch: add uninitialized pointer with __free attribute check
From: Ally Heev @ 2025-11-17 3:10 UTC (permalink / raw)
To: Dwaipayan Ray, Lukas Bulwahn, Joe Perches, Jonathan Corbet,
Andy Whitcroft
Cc: workflows, linux-doc, linux-kernel, Dan Carpenter, David Hunter,
Shuah Khan, Viresh Kumar, Nishanth Menon, Stephen Boyd, linux-pm,
dan.j.williams, Geert Uytterhoeven, Ally Heev
uninitialized pointers with __free attribute can cause undefined
behavior as the memory randomly assigned to the pointer is freed
automatically when the pointer goes out of scope.
add check in checkpatch to detect such issues.
Suggested-by: Dan Carpenter <dan.carpenter@linaro.org>
Link: https://lore.kernel.org/all/8a4c0b43-cf63-400d-b33d-d9c447b7e0b9@suswa.mountain/
Acked-by: Dan Williams <dan.j.williams@intel.com>
Signed-off-by: Ally Heev <allyheev@gmail.com>
---
Testing:
ran checkpatch.pl before and after the change on
crypto/asymmetric_keys/x509_public_key.c, which has
both initialized with NULL and uninitialized pointers
---
Changes in v4:
- fixed UNINITIALIZED_PTR_WITH_FREE description
- Link to v3: https://lore.kernel.org/r/20251025-aheev-checkpatch-uninitialized-free-v3-1-a67f72b1c2bd@gmail.com
Changes in v3:
- remove $FreeAttribute
- Link to v2: https://lore.kernel.org/r/20251024-aheev-checkpatch-uninitialized-free-v2-0-16c0900e8130@gmail.com
Changes in v2:
- change cover letter and title to reflect new changes
- fix regex to handle multiple declarations in a single line case
- convert WARN to ERROR for uninitialized pointers
- add a new WARN for pointers initialized with NULL
- NOTE: tried handling multiple declarations on a single line by splitting
them and matching the parts with regex, but, it turned out to be
complex and overkill. Moreover, multi-line declarations pose a threat
- Link to v1: https://lore.kernel.org/r/20251021-aheev-checkpatch-uninitialized-free-v1-1-18fb01bc6a7a@gmail.com
---
Documentation/dev-tools/checkpatch.rst | 5 +++++
scripts/checkpatch.pl | 6 ++++++
2 files changed, 11 insertions(+)
diff --git a/Documentation/dev-tools/checkpatch.rst b/Documentation/dev-tools/checkpatch.rst
index d5c47e560324fb2399a5b1bc99c891ed1de10535..c61a3892a60c13f7c5ba89e969e39a93a3dcd5bc 100644
--- a/Documentation/dev-tools/checkpatch.rst
+++ b/Documentation/dev-tools/checkpatch.rst
@@ -1009,6 +1009,11 @@ Functions and Variables
return bar;
+ **UNINITIALIZED_PTR_WITH_FREE**
+ Pointers with __free attribute should be initialized. Not doing so
+ may lead to undefined behavior as the memory assigned (garbage,
+ in case not initialized) to the pointer is freed automatically
+ when the pointer goes out of scope.
Permissions
-----------
diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
index 92669904eecc7a8d2afd3f2625528e02b6d17cd6..e697d81d71c0b3628f7b59807e8bc40d582621bb 100755
--- a/scripts/checkpatch.pl
+++ b/scripts/checkpatch.pl
@@ -7721,6 +7721,12 @@ sub process {
ERROR("MISSING_SENTINEL", "missing sentinel in ID array\n" . "$here\n$stat\n");
}
}
+
+# check for uninitialized pointers with __free attribute
+ while ($line =~ /\*\s*($Ident)\s+__free\s*\(\s*$Ident\s*\)\s*[,;]/g) {
+ ERROR("UNINITIALIZED_PTR_WITH_FREE",
+ "pointer '$1' with __free attribute should be initialized\n" . $herecurr);
+ }
}
# If we have no input at all, then there is nothing to report on
---
base-commit: 6548d364a3e850326831799d7e3ea2d7bb97ba08
change-id: 20251021-aheev-checkpatch-uninitialized-free-5c39f75e10a1
Best regards,
-----BEGIN PGP SIGNATURE-----
iHUEABYKAB0WIQQBFRpOLrIakF7DYvaWPaLUP9d7HAUCaQ2YPwAKCRCWPaLUP9d7
HDkPAP9+gFqrD4O5qsYZzxGFwfXPAY7F8TM0lfYy7fLNxA2brAEAwLyLuyN0h7qg
N7da1PWuOGK8tKeZ9dR4r3gFdlbZMAo=
=zo4P
-----END PGP SIGNATURE-----
--
Ally Heev <allyheev@gmail.com>
^ permalink raw reply related
* Re: [PATCH] [v3] Documentation: Provide guidelines for tool-generated content
From: Dave Hansen @ 2025-11-17 19:13 UTC (permalink / raw)
To: Thomas Gleixner, Steven Rostedt
Cc: Dave Hansen, dave, Shuah Khan, Kees Cook, Greg Kroah-Hartman,
Miguel Ojeda, NeilBrown, Lorenzo Stoakes, Dan Williams,
Theodore Ts'o, Sasha Levin, Jonathan Corbet, Vlastimil Babka,
workflows, ksummit
In-Reply-To: <877bvqan70.ffs@tglx>
On 11/15/25 15:30, Thomas Gleixner wrote:
>>> As Dave responded to Luis, although that is a good idea, it's out of
>>> scope for this document (for now).
>> I should have said it's out of scope for this patch, not document. The
>> point is that what tag to use for this is a separate discussion.
> Which should be held in the context of this patch to make it complete.
In a perfect world, I totally agree.
But the tag is something we can't really take back. It's like an ABI in
that there needs to be some kind of contract between producers and
consumers, and it's harmful if the contract needs to be revised.
Given how messy the process of formalizing a tag is, I'd really hate
to tie the two things (a policy document and a tag) together
unnecessarily.
^ permalink raw reply
* [PATCH v3] README: restructure with role-based documentation and guidelines
From: Sasha Levin @ 2025-11-17 21:38 UTC (permalink / raw)
To: linux-doc
Cc: corbet, josh, kees, konstantin, linux-kernel, rostedt, workflows,
joe, rdunlap, Sasha Levin
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>
---
Changes in v3:
- Replace "Agentic Coding" terminology with clearer "AI Coding Assistants"
- Add concrete examples of proper Assisted-by tag usage with multiple formats
- Add "Bad examples" section showing anti-patterns to avoid
- Add detailed tool categorization distinguishing specialized vs basic tools
- Add explicit format specification: $AGENT_NAME:$MODEL_VERSION [$TOOL1] ...
- Expand section description to clarify it applies to both AI tools and
developers using AI tools
README | 212 +++++++++++++++++++++++++++++++++++++++---
scripts/checkpatch.pl | 1 +
2 files changed, 202 insertions(+), 11 deletions(-)
diff --git a/README b/README
index fd903645e6de0..3c8a39cb86710 100644
--- a/README
+++ b/README
@@ -1,18 +1,208 @@
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
+* AI Coding Assistants - 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
+
+AI Coding Assistants
+--------------------
+
+Guidelines for AI assistants and developers using AI tools when working
+with kernel code:
+
+* 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:
+ Format: Assisted-by: $AGENT_NAME:$MODEL_VERSION [$TOOL1] [$TOOL2] ...
+
+Examples of Proper Attribution:
+
+Good examples:
+ Assisted-by: AI-Tool:model-version-1.0 coccinelle
+ Assisted-by: AI-Assistant:v2.5.0
+ Assisted-by: Code-Helper:model-2024-04-09 sparse smatch
+ Assisted-by: ML-Agent:version-2024-11
+
+Bad examples (DO NOT USE):
+ Assisted-by: AI # Too vague
+ Assisted-by: AI-Tool coccinelle git # Don't list basic tools
+ Signed-off-by: AI Assistant <ai@...> # NEVER - AI cannot sign off
+
+Tool Categories:
+
+Specialized tools (SHOULD list if used):
+ - coccinelle: Semantic patch tool for C code transformations
+ - sparse: Semantic checker for C programs
+ - smatch: Static analysis tool for C
+ - cppcheck: Static analysis for C/C++
+ - clang-tidy: Clang-based linter
+ - Custom analysis scripts you created
+
+Basic tools (DON'T list - assumed to be used):
+ - git: Version control
+ - checkpatch.pl: Kernel style checker
+ - gcc/clang: Compilers
+ - make: Build system
+ - Standard editors (vim, emacs, nano, etc.)
+
+
+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
diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
index 92669904eecc7..6e92e0f46ae61 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:
)};
--
2.51.0
^ permalink raw reply related
* Re: [PATCH v3] README: restructure with role-based documentation and guidelines
From: Bagas Sanjaya @ 2025-11-18 1:11 UTC (permalink / raw)
To: Sasha Levin, linux-doc
Cc: corbet, josh, kees, konstantin, linux-kernel, rostedt, workflows,
joe, rdunlap
In-Reply-To: <20251117213801.4077535-1-sashal@kernel.org>
[-- Attachment #1: Type: text/plain, Size: 706 bytes --]
On Mon, Nov 17, 2025 at 04:38:01PM -0500, Sasha Levin wrote:
> +* Build the kernel: make defconfig && make -j$(nproc)
See Documentation/admin-guide/quickly-build-trimmed-linux.rst.
> +* Attribution: Agents MUST add Assisted-by tag:
> + Format: Assisted-by: $AGENT_NAME:$MODEL_VERSION [$TOOL1] [$TOOL2] ...
> +
> +Examples of Proper Attribution:
> +
> +Good examples:
> + Assisted-by: AI-Tool:model-version-1.0 coccinelle
> + Assisted-by: AI-Assistant:v2.5.0
> + Assisted-by: Code-Helper:model-2024-04-09 sparse smatch
> + Assisted-by: ML-Agent:version-2024-11
So mentioning LLM version is strictly required?
Thanks.
--
An old man doll... just what I always wanted! - Clara
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]
^ permalink raw reply
* Re: [PATCH v3] README: restructure with role-based documentation and guidelines
From: Sasha Levin @ 2025-11-18 2:24 UTC (permalink / raw)
To: Bagas Sanjaya
Cc: linux-doc, corbet, josh, kees, konstantin, linux-kernel, rostedt,
workflows, joe, rdunlap
In-Reply-To: <aRvHpfke8hZ--AHF@archie.me>
On Tue, Nov 18, 2025 at 08:11:01AM +0700, Bagas Sanjaya wrote:
>On Mon, Nov 17, 2025 at 04:38:01PM -0500, Sasha Levin wrote:
>> +* Build the kernel: make defconfig && make -j$(nproc)
>
>See Documentation/admin-guide/quickly-build-trimmed-linux.rst.
ooh nice, I wasn't aware of this one.
>> +* Attribution: Agents MUST add Assisted-by tag:
>> + Format: Assisted-by: $AGENT_NAME:$MODEL_VERSION [$TOOL1] [$TOOL2] ...
>> +
>> +Examples of Proper Attribution:
>> +
>> +Good examples:
>> + Assisted-by: AI-Tool:model-version-1.0 coccinelle
>> + Assisted-by: AI-Assistant:v2.5.0
>> + Assisted-by: Code-Helper:model-2024-04-09 sparse smatch
>> + Assisted-by: ML-Agent:version-2024-11
>
>So mentioning LLM version is strictly required?
Ideally yes, it'll help us keep track of which tooling is being used, and help
us improve our workflows based on the results we're seeing from different LLMs.
Also keep in mind that these instructions will be used by the LLMs, so it
shouldn't add burden on authors.
A simple prompt of "Update the kernel version in the Makefile to 10.0 and
commit the result" with the updated README gave me the following commit:
commit b3fcd7c2ec1818e3f70c4ee9c4a6f5b210e567dc (HEAD)
Author: Sasha Levin <sashal@kernel.org>
Date: Mon Nov 17 21:21:14 2025 -0500
Makefile: Update kernel version to 10.0
Update VERSION to 10 and PATCHLEVEL to 0, and clear EXTRAVERSION
to set the kernel version to 10.0.
Assisted-by: Claude:sonnet-4-5-20250929
--
Thanks,
Sasha
^ permalink raw reply
* Re: [PATCH v3] README: restructure with role-based documentation and guidelines
From: Geert Uytterhoeven @ 2025-11-18 8:08 UTC (permalink / raw)
To: Sasha Levin
Cc: Bagas Sanjaya, linux-doc, corbet, josh, kees, konstantin,
linux-kernel, rostedt, workflows, joe, rdunlap
In-Reply-To: <aRvY0QbRzkh94zql@laps>
Hi Sasha,
On Tue, 18 Nov 2025 at 03:24, Sasha Levin <sashal@kernel.org> wrote:
> On Tue, Nov 18, 2025 at 08:11:01AM +0700, Bagas Sanjaya wrote:
> >On Mon, Nov 17, 2025 at 04:38:01PM -0500, Sasha Levin wrote:
> >> +* Build the kernel: make defconfig && make -j$(nproc)
> >
> >See Documentation/admin-guide/quickly-build-trimmed-linux.rst.
>
> ooh nice, I wasn't aware of this one.
>
> >> +* Attribution: Agents MUST add Assisted-by tag:
> >> + Format: Assisted-by: $AGENT_NAME:$MODEL_VERSION [$TOOL1] [$TOOL2] ...
> >> +
> >> +Examples of Proper Attribution:
> >> +
> >> +Good examples:
> >> + Assisted-by: AI-Tool:model-version-1.0 coccinelle
> >> + Assisted-by: AI-Assistant:v2.5.0
> >> + Assisted-by: Code-Helper:model-2024-04-09 sparse smatch
> >> + Assisted-by: ML-Agent:version-2024-11
> >
> >So mentioning LLM version is strictly required?
>
> Ideally yes, it'll help us keep track of which tooling is being used, and help
> us improve our workflows based on the results we're seeing from different LLMs.
Apparently we already have two users, without version numbers ;-)
- https://web.git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=913e65a2fe1a16fa253c4a016e2306b2cf9ffef8
Assisted-by: Google Gemini
- https://web.git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=525cebedb32a87fa48584bc44e14170beb2c10d1
Assisted-by: Daniel Borkmann <dborkmann@redhat.com>
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
^ permalink raw reply
* Re: [PATCH v3] README: restructure with role-based documentation and guidelines
From: Jonathan Corbet @ 2025-11-18 16:35 UTC (permalink / raw)
To: Sasha Levin, linux-doc
Cc: josh, kees, konstantin, linux-kernel, rostedt, workflows, joe,
rdunlap, Sasha Levin
In-Reply-To: <20251117213801.4077535-1-sashal@kernel.org>
Sasha Levin <sashal@kernel.org> writes:
> 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>
> ---
> Changes in v3:
> - Replace "Agentic Coding" terminology with clearer "AI Coding Assistants"
> - Add concrete examples of proper Assisted-by tag usage with multiple formats
> - Add "Bad examples" section showing anti-patterns to avoid
> - Add detailed tool categorization distinguishing specialized vs basic tools
> - Add explicit format specification: $AGENT_NAME:$MODEL_VERSION [$TOOL1] ...
> - Expand section description to clarify it applies to both AI tools and
> developers using AI tools
>
> README | 212 +++++++++++++++++++++++++++++++++++++++---
> scripts/checkpatch.pl | 1 +
> 2 files changed, 202 insertions(+), 11 deletions(-)
Overall I really like this change. We could quibble forever about the
details, but that's probably not worthwhile.
That said, I have one quibble :)
> +Examples of Proper Attribution:
> +
> +Good examples:
> + Assisted-by: AI-Tool:model-version-1.0 coccinelle
> + Assisted-by: AI-Assistant:v2.5.0
> + Assisted-by: Code-Helper:model-2024-04-09 sparse smatch
> + Assisted-by: ML-Agent:version-2024-11
> +
> +Bad examples (DO NOT USE):
> + Assisted-by: AI # Too vague
> + Assisted-by: AI-Tool coccinelle git # Don't list basic tools
> + Signed-off-by: AI Assistant <ai@...> # NEVER - AI cannot sign off
I don't think this belongs here - we don't have examples of good SOB
lines - or of anything else. What this needs, instead, is a link to
Dave's tools document once that goes in.
(We also, in truth, do not yet have a consensus on what the attribution
tags should be, and here isn't the place to try to form one.)
Thanks,
jon
^ permalink raw reply
* Re: [PATCH v3] README: restructure with role-based documentation and guidelines
From: Kees Cook @ 2025-11-18 16:49 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Sasha Levin, linux-doc, josh, konstantin, linux-kernel, rostedt,
workflows, joe, rdunlap
In-Reply-To: <87wm3n47u6.fsf@trenco.lwn.net>
On Tue, Nov 18, 2025 at 09:35:29AM -0700, Jonathan Corbet wrote:
> That said, I have one quibble :)
>
> > +Examples of Proper Attribution:
> > +
> > +Good examples:
> > + Assisted-by: AI-Tool:model-version-1.0 coccinelle
> > + Assisted-by: AI-Assistant:v2.5.0
> > + Assisted-by: Code-Helper:model-2024-04-09 sparse smatch
> > + Assisted-by: ML-Agent:version-2024-11
> > +
> > +Bad examples (DO NOT USE):
> > + Assisted-by: AI # Too vague
> > + Assisted-by: AI-Tool coccinelle git # Don't list basic tools
> > + Signed-off-by: AI Assistant <ai@...> # NEVER - AI cannot sign off
>
> I don't think this belongs here - we don't have examples of good SOB
> lines - or of anything else. What this needs, instead, is a link to
> Dave's tools document once that goes in.
>
> (We also, in truth, do not yet have a consensus on what the attribution
> tags should be, and here isn't the place to try to form one.)
Agreed -- I love the new sections, but we need to drop the Assisted-by
portion until we've had the in-person discussions at Maintainers/LPC.
-Kees
--
Kees Cook
^ permalink raw reply
* Re: [PATCH v3] README: restructure with role-based documentation and guidelines
From: Sasha Levin @ 2025-11-18 16:52 UTC (permalink / raw)
To: Jonathan Corbet
Cc: linux-doc, josh, kees, konstantin, linux-kernel, rostedt,
workflows, joe, rdunlap
In-Reply-To: <87wm3n47u6.fsf@trenco.lwn.net>
On Tue, Nov 18, 2025 at 09:35:29AM -0700, Jonathan Corbet wrote:
>Sasha Levin <sashal@kernel.org> writes:
>
>> 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>
>> ---
>> Changes in v3:
>> - Replace "Agentic Coding" terminology with clearer "AI Coding Assistants"
>> - Add concrete examples of proper Assisted-by tag usage with multiple formats
>> - Add "Bad examples" section showing anti-patterns to avoid
>> - Add detailed tool categorization distinguishing specialized vs basic tools
>> - Add explicit format specification: $AGENT_NAME:$MODEL_VERSION [$TOOL1] ...
>> - Expand section description to clarify it applies to both AI tools and
>> developers using AI tools
>>
>> README | 212 +++++++++++++++++++++++++++++++++++++++---
>> scripts/checkpatch.pl | 1 +
>> 2 files changed, 202 insertions(+), 11 deletions(-)
>
>Overall I really like this change. We could quibble forever about the
>details, but that's probably not worthwhile.
Thanks Jon!
What would you say about taking this patch (assuming this falls under the
Documentation subsystem) if I completely drop the AI parts for now?
>That said, I have one quibble :)
>
>> +Examples of Proper Attribution:
>> +
>> +Good examples:
>> + Assisted-by: AI-Tool:model-version-1.0 coccinelle
>> + Assisted-by: AI-Assistant:v2.5.0
>> + Assisted-by: Code-Helper:model-2024-04-09 sparse smatch
>> + Assisted-by: ML-Agent:version-2024-11
>> +
>> +Bad examples (DO NOT USE):
>> + Assisted-by: AI # Too vague
>> + Assisted-by: AI-Tool coccinelle git # Don't list basic tools
>> + Signed-off-by: AI Assistant <ai@...> # NEVER - AI cannot sign off
>
>I don't think this belongs here - we don't have examples of good SOB
>lines - or of anything else. What this needs, instead, is a link to
>Dave's tools document once that goes in.
Makes sense.
>(We also, in truth, do not yet have a consensus on what the attribution
>tags should be, and here isn't the place to try to form one.)
Ack - I've posted this v3 in response to tglx's ask on Dave's doc about having
a standard tag for this to gather more input prior to LPC.
--
Thanks,
Sasha
^ permalink raw reply
page: next (older) | prev (newer) | latest
- recent:[subjects (threaded)|topics (new)|topics (active)]
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox