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

[Sasha Levin <sashal@kernel.org>]

On Tue, Nov 18, 2025 at 09:35:29AM -0700, Jonathan Corbet wrote:
>Sasha Levin <sashal@kernel.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@kernel.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