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

Lee Jones
2026-01-15T15:04:24Z

On Tue, 13 Jan 2026, Dave Hansen wrote:

> On 1/13/26 02:36, Lee Jones wrote:
> ...
> >> +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.
> >
> > Parsing ... okay, that took a few goes. How about:
> >
> > Even if disclosure of your tool isn't mandated, providing this context
> > often helps reviewers evaluate your contribution more effectively.
> > Clear documentation of your workflow ensures a faster review with less
> > contention.
> I agree that the sentence is hard to parse. But, I want to explicitly
> say "out of scope" to tie this in to the rest of the section. How about
> this?
>
> Even if your tool use is out of scope, consider disclosing how
> you used the tool. Clear documentation of your workflow often
> helps reviewers do their jobs more efficiently.
>
> BTW, I do think we're well into diminishing returns territory. I'll roll
> this into a v6 if there's a v6. But, if it's pulled in as-is, I think
> the original can stay without causing too much harm.

Agree. Thanks for considering.

> ...>> +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.
> >
> > Nit: Suggest removing the sporadic use of full-stops (periods) across all lists.
> >
> > Or add them everywhere - so long as it's consistent.
>
> The rule that I read is that when the bullets are full, complete
> sentences, you should use periods. When they are just nouns or shards of
> sentences, leave off the periods.
>
> I _think_ that's the consensus for how to punctuate bulleted list items.
>
> But I don't remember where I read that, if it was in Documentation/
> somewhere or it was some random rule on the Internet I decided to apply.

The non-consistency of it makes me twitch, but perhaps just my issue.

--
Lee Jones [李琼斯]