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] [day] [month] [year] [list]

Message-ID: <20260115150416.GE2842980@google.com>
Date: Thu, 15 Jan 2026 15:04:16 +0000
From: Lee Jones <lee@...nel.org>
To: Dave Hansen <dave.hansen@...el.com>
Cc: 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, 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 [李琼斯]