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

[Geert Uytterhoeven <geert@linux-m68k.org>]

On Tue, 13 Jan 2026 at 19:05, Dave Hansen <dave.hansen@intel.com> 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.
>
> ...>> +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.

Or for the latter: use commas for all but the last one, and finish
with a period.

Just my 0.02€, from an old LaTeX user...

P.S. Linus seems to disagree, as he consistently drops the carefully
     placed commas and periods when merging my pull requests...

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