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

[Lee Jones]

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 [李琼斯]