linux-kernel - Re: [PATCH v3] README: restructure with role-based documentation and guidelines

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: <aRykPFH0sIfmARvs@laps>
Date: Tue, 18 Nov 2025 11:52:12 -0500
From: Sasha Levin <sashal@...nel.org>
To: Jonathan Corbet <corbet@....net>
Cc: linux-doc@...r.kernel.org, josh@...htriplett.org, kees@...nel.org,
	konstantin@...uxfoundation.org, linux-kernel@...r.kernel.org,
	rostedt@...dmis.org, workflows@...r.kernel.org, joe@...ches.com,
	rdunlap@...radead.org
Subject: Re: [PATCH v3] README: restructure with role-based documentation and
 guidelines

On Tue, Nov 18, 2025 at 09:35:29AM -0700, Jonathan Corbet wrote:
>Sasha Levin <sashal@...nel.org> writes:
>
>> Reorganize README to provide targeted documentation paths for different user
>> roles including developers, researchers, security experts, maintainers, and AI
>> coding assistants. Add quick start section and essential docs links.
>>
>> Include proper attribution requirements for AI-assisted contributions using
>> Assisted-by tags with agent details and tools used.
>>
>> Signed-off-by: Sasha Levin <sashal@...nel.org>
>> ---
>> Changes in v3:
>> - Replace "Agentic Coding" terminology with clearer "AI Coding Assistants"
>> - Add concrete examples of proper Assisted-by tag usage with multiple formats
>> - Add "Bad examples" section showing anti-patterns to avoid
>> - Add detailed tool categorization distinguishing specialized vs basic tools
>> - Add explicit format specification: $AGENT_NAME:$MODEL_VERSION [$TOOL1] ...
>> - Expand section description to clarify it applies to both AI tools and
>>   developers using AI tools
>>
>>  README                | 212 +++++++++++++++++++++++++++++++++++++++---
>>  scripts/checkpatch.pl |   1 +
>>  2 files changed, 202 insertions(+), 11 deletions(-)
>
>Overall I really like this change.  We could quibble forever about the
>details, but that's probably not worthwhile.

Thanks Jon!

What would you say about taking this patch (assuming this falls under the
Documentation subsystem) if I completely drop the AI parts for now?

>That said, I have one quibble :)
>
>> +Examples of Proper Attribution:
>> +
>> +Good examples:
>> +  Assisted-by: AI-Tool:model-version-1.0 coccinelle
>> +  Assisted-by: AI-Assistant:v2.5.0
>> +  Assisted-by: Code-Helper:model-2024-04-09 sparse smatch
>> +  Assisted-by: ML-Agent:version-2024-11
>> +
>> +Bad examples (DO NOT USE):
>> +  Assisted-by: AI                          # Too vague
>> +  Assisted-by: AI-Tool coccinelle git      # Don't list basic tools
>> +  Signed-off-by: AI Assistant <ai@...>     # NEVER - AI cannot sign off
>
>I don't think this belongs here - we don't have examples of good SOB
>lines - or of anything else.  What this needs, instead, is a link to
>Dave's tools document once that goes in.

Makes sense.

>(We also, in truth, do not yet have a consensus on what the attribution
>tags should be, and here isn't the place to try to form one.)

Ack - I've posted this v3 in response to tglx's ask on Dave's doc about having
a standard tag for this to gather more input prior to LPC.

-- 
Thanks,
Sasha