[PATCH] [v3] Documentation: Provide guidelines for tool-generated content

[PATCH] [v3] Documentation: Provide guidelines for tool-generated content

[Dave Hansen]

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

Re: [PATCH] [v3] Documentation: Provide guidelines for tool-generated content

[Luis Chamberlain]

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

Re: [PATCH] [v3] Documentation: Provide guidelines for tool-generated content

[Dave Hansen]

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!

Re: [PATCH] [v3] Documentation: Provide guidelines for tool-generated content

[SeongJae Park]

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)

Re: [PATCH] [v3] Documentation: Provide guidelines for tool-generated content

[Dave Hansen]

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!

Re: [PATCH] [v3] Documentation: Provide guidelines for tool-generated content

[dan.j.williams]

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>

Re: [PATCH] [v3] Documentation: Provide guidelines for tool-generated content

[Thomas Gleixner]

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

Re: [PATCH] [v3] Documentation: Provide guidelines for tool-generated content

[Steven Rostedt]

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

Re: [PATCH] [v3] Documentation: Provide guidelines for tool-generated content

[Steven Rostedt]

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

Re: [PATCH] [v3] Documentation: Provide guidelines for tool-generated content

[Thomas Gleixner]

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

Re: [PATCH] [v3] Documentation: Provide guidelines for tool-generated content

[Rafael J. Wysocki]

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.

Re: [PATCH] [v3] Documentation: Provide guidelines for tool-generated content

[Kees Cook]

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

Re: [PATCH] [v3] Documentation: Provide guidelines for tool-generated content

[Steven Rostedt]

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

Re: [PATCH] [v3] Documentation: Provide guidelines for tool-generated content

[Steven Rostedt]

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

Re: [PATCH] [v3] Documentation: Provide guidelines for tool-generated content

[Dave Hansen]

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.

Re: [PATCH] [v3] Documentation: Provide guidelines for tool-generated content

[Steven Rostedt]

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

Re: [PATCH] [v3] Documentation: Provide guidelines for tool-generated content

[Randy Dunlap]

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