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: <87wm3n47u6.fsf@trenco.lwn.net>
Date: Tue, 18 Nov 2025 09:35:29 -0700
From: Jonathan Corbet <corbet@....net>
To: Sasha Levin <sashal@...nel.org>, linux-doc@...r.kernel.org
Cc: 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, Sasha
 Levin <sashal@...nel.org>
Subject: Re: [PATCH v3] README: restructure with role-based documentation
 and guidelines

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.

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.

(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.)

Thanks,

jon