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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <CAMuHMdUJX4DZzUuy9k8WBtRJm2QHdN=xQ9zfXudTPdHyLRvUrw@mail.gmail.com>
Date: Tue, 13 Jan 2026 19:55:06 +0100
From: Geert Uytterhoeven <geert@...ux-m68k.org>
To: Dave Hansen <dave.hansen@...el.com>
Cc: Lee Jones <lee@...nel.org>, Dave Hansen <dave.hansen@...ux.intel.com>, 
	linux-kernel@...r.kernel.org, Shuah Khan <shuah@...nel.org>, 
	Kees Cook <kees@...nel.org>, Greg Kroah-Hartman <gregkh@...uxfoundation.org>, 
	Miguel Ojeda <ojeda@...nel.org>, Luis Chamberlain <mcgrof@...nel.org>, SeongJae Park <sj@...nel.org>, 
	Dan Williams <dan.j.williams@...el.com>, Steven Rostedt <rostedt@...dmis.org>, 
	"Paul E . McKenney" <paulmck@...nel.org>, Simon Glass <simon.glass@...onical.com>, 
	NeilBrown <neilb@...mail.net>, Lorenzo Stoakes <lorenzo.stoakes@...cle.com>, 
	"Theodore Ts'o" <tytso@....edu>, Sasha Levin <sashal@...nel.org>, Jonathan Corbet <corbet@....net>, 
	Vlastimil Babka <vbabka@...e.cz>, workflows@...r.kernel.org, ksummit@...ts.linux.dev
Subject: Re: [PATCH] [v5] Documentation: Provide guidelines for tool-generated content

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