linux-kernel - Re: [PATCH v2 1/2] 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] [day] [month] [year] [list]

Message-ID: <aJoQs_5Mp7-LAtTS@lappy>
Date: Mon, 11 Aug 2025 11:48:03 -0400
From: Sasha Levin <sashal@...nel.org>
To: Geert Uytterhoeven <geert@...ux-m68k.org>
Cc: corbet@....net, josh@...htriplett.org, kees@...nel.org,
	konstantin@...uxfoundation.org, linux-doc@...r.kernel.org,
	linux-kernel@...r.kernel.org, rostedt@...dmis.org,
	workflows@...r.kernel.org
Subject: Re: [PATCH v2 1/2] README: restructure with role-based documentation
 and guidelines

On Mon, Aug 11, 2025 at 10:22:34AM +0200, Geert Uytterhoeven wrote:
>Hi Sasha,
>
>On Sun, 10 Aug 2025 at 10:09, Sasha Levin <sashal@...nel.org> wrote:
>> 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>
>
>Thanks for your patch!
>
>> --- a/README
>> +++ b/README
>
>> +Who Are You?
>> +============
>> +
>> +Find your role below:
>> +
>> +* New Kernel Developer - Getting started with kernel development
>> +* Academic Researcher - Studying kernel internals and architecture
>> +* Security Expert - Hardening and vulnerability analysis
>> +* Backport/Maintenance Engineer - Maintaining stable kernels
>> +* System Administrator - Configuring and troubleshooting
>> +* Maintainer - Leading subsystems and reviewing patches
>
>Kernel Maintainer?
>Driver/Subsystem Maintainer?

I tried to use similar terms to the ones used by the rest of our docs.
In this case, the CoC interpertation actually defines this term :)

	The Code of Conduct uses the term "maintainers" numerous times.
	In the kernel community, a "maintainer" is anyone who is
	responsible for a subsystem, driver, or file, and is listed in
	the MAINTAINERS file in the kernel source tree.

So I just went with "Maintainer".

>> +* Hardware Vendor - Writing drivers for new hardware
>> +* Distribution Maintainer - Packaging kernels for distros
>> +* Agentic Coding - AI assistants working with kernel code
>
>Given the extensive split, what about normal (existing) kernel
>developers?

Those people don't read the docs anyway :p

How about something like:

Existing Kernel Developer
-------------------------

Continue advancing your kernel development expertise:

* Locking and Concurrency: Documentation/locking/index.rst
* RCU (Read-Copy Update): Documentation/RCU/index.rst
* Subsystem APIs: Documentation/driver-api/index.rst
* Performance Analysis: Documentation/trace/index.rst
* Testing Infrastructure: Documentation/dev-tools/testing-overview.rst
* Patch Series Management: Documentation/process/5.Posting.rst
* Maintainer Handbooks: Documentation/process/maintainer-handbooks.rst
* Cross-Architecture Development: Documentation/arch/index.rst
* Kernel Debugging: Documentation/process/debugging/kgdb.rst

-- 
Thanks,
Sasha