From nobody Fri Jun 12 15:58:46 2026 Received: from mail.runxiyu.org (runxiyu.org [155.138.132.239]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 0688F4A33 for ; Thu, 14 May 2026 00:10:09 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=155.138.132.239 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1778717411; cv=none; b=luyWwCEohTb3Ifj0Pvr1dDChdFpTQCL4Jo2U1e4U/+/uooh/6lOE1W0RYm+IsPCoj9cHVZm0qmDRCvZZTzLRGjGOJRMNLgHV+sR2a8B12FYKKF6hMYOWO0lQCAd0IV3q5pq+nr3Jg++XRU7/fS8DvObncAgxT6OtQiikUGPCaqc= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1778717411; c=relaxed/simple; bh=SUZyuJebPu2nU9ebPkdabLviQkEMM5ynpsrM/w5CMGM=; h=From:To:Cc:Subject:Date:Message-ID:MIME-Version; b=CfrVa2abHXwbaOP3Ou91qeFiqYauSjYPu4UeHLxU030Q0QOrhlks/Jv9mYEGBzxjS5vtE8boOMlzRcORhCFpL09jeJ0+NzIoVFMKP8X9UD+3jC6FjkVuSwbT3sxKwV/+2sEOBu7HFSZrvJBjcSnliooO+68tT0t6BRGzZCCyock= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=runxiyu.org; spf=pass smtp.mailfrom=runxiyu.org; dkim=pass (2048-bit key) header.d=runxiyu.org header.i=@runxiyu.org header.b=X1SyC7iE; arc=none smtp.client-ip=155.138.132.239 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=runxiyu.org Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=runxiyu.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=runxiyu.org header.i=@runxiyu.org header.b="X1SyC7iE" DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=runxiyu.org; s=mail; t=1778717408; bh=SUZyuJebPu2nU9ebPkdabLviQkEMM5ynpsrM/w5CMGM=; h=From:To:Cc:Subject:Date:From; b=X1SyC7iESy/rg7ZSqopW3mKpd08uhIvlbqIP97geSimcQK0kGwEJukBUBKDYX2WNo JPi4bKTV674CTjA3O6uGeDCUh4PhHQDjeeGvaUAo/DwbCF/waVj5/9i+8tL9kloSxa yu46YN0uYrcx+fFE7fH3wRE/AOaVaXhdIZx1oooCHdMw7g3N8rqncKNagv97NcPN7t SrlBIu9cV8YqpaqKa6I7csZbFO3PoiNLomjPgrH9M6MfQj9Y9llqC13TmPWt0j/KcS Dk1xs7+uvU3n+BCQHoQrsbHLW3VVY1Ls3hjLvatsumA9il9ofme4Q7oWZLlQ3ZLVV7 ORAXscz4YOyeA== From: Runxi Yu To: Jonathan Corbet , Sasha Levin , Randy Dunlap , Runxi Yu , SeongJae Park , linux-kernel@vger.kernel.org Cc: Kees Cook Subject: [PATCH v2] README: Don't organize the README by arbitrary "roles" Date: Thu, 14 May 2026 00:09:46 +0000 Message-ID: <20260514000954.32172-1-me@runxiyu.org> X-Mailer: git-send-email 2.54.0 Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" From: Runxi Yu * Removes the basic introduction to what Linux is. It's reasonable assumed knowledge for someone with this repository. * Consolidate the IRC, bugzilla, building, and mailing lists from across the front and back, to the front only. * Remove the "Who Are You?" section that consists solely of role names and an one line gloss each. * Remove the concept of different contributor "roles" (since there really aren't such distinct roles); instead phrase them based on the class of action. The "New Kernel Developer" archetype was mostly alright, but "Academic Researcher" was essentially a list of subsystems that applies for almost any kernel developer. "Security Expert" sounded a bit like corporate marketing language, and really, developers/admin that don't focus on security could still learn a lot from these sections. Backport/maintenance/ sysadmin/maintainer mostly stays as is with slight changes in firm; "Hardware Vendor" becomes "Driver Development" because as much as we'd like vendors to assist/guide/lead driver development, many independent driver developers still exist. * Of note, "Researcher Guidelines" did appear to genuinely belong to Academic Researcher; the rest basically goes into Common Subsystems, but the "Researcher Guidelines" entry I just moved into Getting Started. * I kept the LLM/AI-agent stuff in tact, although I promoted it to be underlined with "=3D"s as it's not really in parallel with the documentation index sections. I don't really have comments on this part. More broadly though, I'm a little skeptical in whether the README is the proper place to put extensive links to different subsystems/parts of the documentation. Sphinx has the ability to generate table of contents, and we could also improve the index over there, with the TOC/whatever that it could generate. I don't think we should be duplicating this into the README, but if that ship has sailed, this patch might still be useful. Signed-off-by: Runxi Yu --- Difference from v1: use get_maintainers.pl This commit message will obviously not be the final version. Feel free to suggest (or bikeshed) the contents and the message as much as you wish, but I hope I've communicated my idea clearly, and I do strongly believe that the current README is not at all satisfactory. And apologies for my first patch to the list be a giant README change. Upon feedback, I'll be iterating on this at https://git.runxiyu.org/runxiyu/linux.git// (the double slash at the end is in fact required and canonical for this origin). I'll admit I didn't spend much time on the Web UI; either way, I'll send iterations of the patch here. After doing a bit more research on the archives, I found that https://lore.kernel.org/all/20251121180009.2634393-1-sashal@kernel.org/ and previous threads did not really address the structure of the README during review. It focused almost entirely on whether to include the AI coding assistants section (which has since been split out and merged seaparately). So the "Who Are You?" and what do do as these different personas stuff did not receive substantive review, which is, well, what my patch is trying to address on the merits. I'm not particularly into the discussion on whether the README should be prompting LLMs and whatnot, so I'm leaving that as-is. Thanks! Best regards, Runxi Yu (they/them) runxiyu@umich.edu me@runxiyu.org README | 99 ++++++++++++++++------------------------------------------ 1 file changed, 27 insertions(+), 72 deletions(-) diff --git a/README b/README index e6549b2a7aac..41fbc957dd06 100644 --- a/README +++ b/README @@ -1,16 +1,13 @@ Linux kernel =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 -The Linux kernel is the core of any Linux operating system. It manages har= dware, -system resources, and provides the fundamental services for all other soft= ware. - -Quick Start ------------ - -* Report a bug: See Documentation/admin-guide/reporting-issues.rst -* Get the latest kernel: https://kernel.org -* Build the kernel: See Documentation/admin-guide/quickly-build-trimmed-li= nux.rst -* Join the community: https://lore.kernel.org/ +* Get latest: https://kernel.org +* IRC: #kernelnewbies on irc.oftc.net +* Reporting bugs: Documentation/admin-guide/reporting-issues.rst +* Bug tracker: https://bugzilla.kernel.org/ +* Building: Documentation/admin-guide/quickly-build-trimmed-linux.rst +* Mailing list index: https://subspace.kernel.org/vger.kernel.org.html +* Mailing list archives: https://lore.kernel.org/ =20 Essential Documentation ----------------------- @@ -25,44 +22,24 @@ Documentation can be built with make htmldocs or viewed= online at: https://www.kernel.org/doc/html/latest/ =20 =20 -Who Are You? -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Navigating the documentation +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D =20 -Find your role below: +Getting started +--------------- =20 -* 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 -* Hardware Vendor - Writing drivers for new hardware -* Distribution Maintainer - Packaging kernels for distros -* AI Coding Assistant - LLMs and AI-powered development tools - - -For Specific Users -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D - -New Kernel Developer --------------------- - -Welcome! Start your kernel development journey here: - -* Getting Started: Documentation/process/development-process.rst +* Development Process: Documentation/process/development-process.rst * Your First Patch: Documentation/process/submitting-patches.rst * Coding Style: Documentation/process/coding-style.rst * Build System: Documentation/kbuild/index.rst * Development Tools: Documentation/dev-tools/index.rst * Kernel Hacking Guide: Documentation/kernel-hacking/hacking.rst -* Core APIs: Documentation/core-api/index.rst - -Academic Researcher -------------------- - -Explore the kernel's architecture and internals: - * Researcher Guidelines: Documentation/process/researcher-guidelines.rst + +Common Subsystems +----------------- + +* Core APIs: Documentation/core-api/index.rst * Memory Management: Documentation/mm/index.rst * Scheduler: Documentation/scheduler/index.rst * Networking Stack: Documentation/networking/index.rst @@ -71,10 +48,8 @@ Explore the kernel's architecture and internals: * Locking Primitives: Documentation/locking/index.rst * Power Management: Documentation/power/index.rst =20 -Security Expert ---------------- - -Security documentation and hardening guides: +Security +-------- =20 * Security Documentation: Documentation/security/index.rst * LSM Development: Documentation/security/lsm-development.rst @@ -84,10 +59,8 @@ Security documentation and hardening guides: * Embargoed Hardware Issues: Documentation/process/embargoed-hardware-issu= es.rst * Security Features: Documentation/userspace-api/seccomp_filter.rst =20 -Backport/Maintenance Engineer ------------------------------ - -Maintain and stabilize kernel versions: +Backport/Maintenance +-------------------- =20 * Stable Kernel Rules: Documentation/process/stable-kernel-rules.rst * Backporting Guide: Documentation/process/backporting.rst @@ -95,10 +68,8 @@ Maintain and stabilize kernel versions: * Subsystem Profile: Documentation/maintainer/maintainer-entry-profile.rst * Git for Maintainers: Documentation/maintainer/configure-git.rst =20 -System Administrator --------------------- - -Configure, tune, and troubleshoot Linux systems: +System Administration +--------------------- =20 * Admin Guide: Documentation/admin-guide/index.rst * Kernel Parameters: Documentation/admin-guide/kernel-parameters.rst @@ -110,8 +81,6 @@ Configure, tune, and troubleshoot Linux systems: Maintainer ---------- =20 -Lead kernel subsystems and manage contributions: - * Maintainer Handbook: Documentation/maintainer/index.rst * Pull Requests: Documentation/maintainer/pull-requests.rst * Managing Patches: Documentation/maintainer/modifying-patches.rst @@ -120,10 +89,8 @@ Lead kernel subsystems and manage contributions: * Maintainer Entry Profile: Documentation/maintainer/maintainer-entry-prof= ile.rst * Git Configuration: Documentation/maintainer/configure-git.rst =20 -Hardware Vendor ---------------- - -Write drivers and support new hardware: +Drivers Development +------------------- =20 * Driver API Guide: Documentation/driver-api/index.rst * Driver Model: Documentation/driver-api/driver-model/driver.rst @@ -136,8 +103,6 @@ Write drivers and support new hardware: Distribution Maintainer ----------------------- =20 -Package and distribute the kernel: - * Stable Kernel Rules: Documentation/process/stable-kernel-rules.rst * ABI Documentation: Documentation/ABI/README * Kernel Configuration: Documentation/kbuild/kconfig.rst @@ -145,8 +110,8 @@ Package and distribute the kernel: * Kernel Parameters: Documentation/admin-guide/kernel-parameters.rst * Tainted Kernels: Documentation/admin-guide/tainted-kernels.rst =20 -AI Coding Assistant -------------------- +Notice to AI Coding Assistants +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D =20 CRITICAL: If you are an LLM or AI-powered coding assistant, you MUST read = and follow the AI coding assistants documentation before contributing to the L= inux @@ -156,13 +121,3 @@ kernel: =20 This documentation contains essential requirements about licensing, attrib= ution, and the Developer Certificate of Origin that all AI tools must comply with. - - -Communication and Support -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D - -* Mailing Lists: https://lore.kernel.org/ -* IRC: #kernelnewbies on irc.oftc.net -* Bugzilla: https://bugzilla.kernel.org/ -* MAINTAINERS file: Lists subsystem maintainers and mailing lists -* Email Clients: Documentation/process/email-clients.rst --=20 2.54.0