From nobody Tue Jun 16 17:01:32 2026 Received: from mail-wm1-f52.google.com (mail-wm1-f52.google.com [209.85.128.52]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 5E7AA39BFFF for ; Thu, 30 Apr 2026 09:56:03 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.128.52 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1777542965; cv=none; b=dA89SJz+ttLcy1bR01hXbuwLA1fuge3yodA3o+PtrdHOGWegpKdQVP9Nqp4NQkTokfz12GsjAEziCinMlHeX82xKWY/Mv2S4/A31LpuxSVxgYMTo/u+tcvHF5es+nZiMF9m5YSeW045uKpxQrSVgbbKBC8N9SmOx2raIRiGk2Dk= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1777542965; c=relaxed/simple; bh=3vNj8k0iTyOdrHuhb3c9skbu1BKl0hGSCtj2ah8A3Mk=; h=Message-ID:Date:MIME-Version:To:Cc:From:Subject:Content-Type; b=M0d0zpnMMmrvYXS65auEteduHDsrXZ8wMyXxUgfzFw4WhFjjLhb5qMIrP3M9E2BN7YK7nQsUNlfGPoEUlkH2XdcsR4ORhnaweYery2O7PHqbN+UVPQqMmaSypJCYSo7BFcWH9xN9rVnv3dAgxZtsW794qI2Y/+fZ700RsAvue/g= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=VDliSXAL; arc=none smtp.client-ip=209.85.128.52 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="VDliSXAL" Received: by mail-wm1-f52.google.com with SMTP id 5b1f17b1804b1-4891c0620bcso4976455e9.1 for ; Thu, 30 Apr 2026 02:56:03 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1777542962; x=1778147762; darn=vger.kernel.org; h=content-transfer-encoding:subject:from:cc:to:content-language :user-agent:mime-version:date:message-id:from:to:cc:subject:date :message-id:reply-to; bh=YcDe02dKeO7fVyNYvA0s4la/KbT2/RlEhU0ejMBaHZ8=; b=VDliSXALgprx31v/8fZuiocS5Lrl6Fl7oEPJTy6ePgPPJSt351IhHcOvKhLxw73AH8 OmpnVWZjI7bafx3EERqlpgY3CEYmY05iEY98a6d7KHZpgXUiLkNuT/5A7uh1DCmPGiQ7 ZsPBOIIZO75I/hzsgU1t2s9RFj0hekwlRhaMPfU89ojJC78FM8xGECTciFDV1/l113ZR 2gwhS9kgD5TqLVLu6dN1Q1nAQ5/O6l7RElBcmC2LVnUQjq3KLNpTNjyRGjtAPNg7kKz0 urMVUur1Ttz0O3SaPDgkxpP0IaXCRuiOAnLaSgWuZRhhazFOrgcQ9KOErnDBm4EB63I0 AODQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1777542962; x=1778147762; h=content-transfer-encoding:subject:from:cc:to:content-language :user-agent:mime-version:date:message-id:x-gm-gg:x-gm-message-state :from:to:cc:subject:date:message-id:reply-to; bh=YcDe02dKeO7fVyNYvA0s4la/KbT2/RlEhU0ejMBaHZ8=; b=a0/1S0DMVpn1e/FEdlOaF07Kf+v4TLPh/isNq6devE3XYLYqGb0Ifl5hQVeL/JSyBd bYjmI7CR96xqW2c+7FtV8jKJs7Af/gOvF3R5I2qp9mun4nQaG5QpK7935aARH60l3gLR SQdv1ifvAUgJAAmR+/aGA7I6GmJqyoQXBxov7nas2c/pTTr/1fqnLR7I1kmg4beWA0tJ m0jvv0fteSoNp6d9aSAYyONl9C/kpe+RHluATuct3IBrUPVT35p4P57kF8c8qKvjzl+V 27Xkk0tjOmKwdbidiHglNPSYYQoamj2DZs1zUpYE/DpTfNMtR0u+kATzLKeRKdQ88VR+ MN3g== X-Forwarded-Encrypted: i=1; AFNElJ/OQ57P+tWYC2KvncTj/fNNBu+fckzez/wIWYLLpebjoSanrO+BUBRDWHrLWAJoNm9S4Vviuj2Xpg1Cy58=@vger.kernel.org X-Gm-Message-State: AOJu0YyBFGg0To1V2foLiUByBghAtqgrdVOHIxvFY4YbEsfwJ71kFM7/ bQsJpDpkAfcQgUT4lw826f5rP8WmZal7BP68Q551q3LkGUiyAWZR9SHn X-Gm-Gg: AeBDieuCPlsgRtOb/6ihVnBPLQZvuHqJSfqrnwUE+jt3dHL1ZWz0TB/lin61lt/ywmp 2KAWBvNUu+bbSneBGeYcjK3hgHnl3o7aP8cOBKHhCivFxKyotm+U+Wc63Cx6ymgYRBI5XJuvMFu DtzU1qe6/h2b4PJfsWAwF3YpKR8uHEDoXFv4QPNfcCU3trp+adA43I71YMQSF0O0twZ1vvbtOTh u0pdk5v7cR+2FrvI7Lb//IVMkG8o9lVqhtSs9w8UWF+91/DBiEPpGJ3Br5vZwtn+UmHT8tGU+PT HPuYkaohcmOluyXVr3s2OExjM4DLuxvxMeziG50D0KYD6+Wy142giXuGAWcoxRxX8jHPcKWkhZn ydqgT+SxIHFktEzpjciUa8vK986xBSnrcGbH14B2tPRDxxo2xnBFLhMs37A/Yq47n9necZR0qPe LuGaLdD3MNSPR3JQ/cMWtZKZ1HHp1psM8hw1Nz0T+/Lo5x7nLErPoZrUUNpw== X-Received: by 2002:a05:600c:4f47:b0:488:b239:77ec with SMTP id 5b1f17b1804b1-48a8451d08amr34589845e9.17.1777542961258; Thu, 30 Apr 2026 02:56:01 -0700 (PDT) Received: from [10.225.92.149] ([37.29.179.221]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-48a7b900af7sm40282125e9.1.2026.04.30.02.55.59 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Thu, 30 Apr 2026 02:56:00 -0700 (PDT) Message-ID: Date: Thu, 30 Apr 2026 11:55:57 +0200 Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 User-Agent: Mozilla Thunderbird Content-Language: en-US To: linux-doc@vger.kernel.org Cc: corbet@lwn.net, linux-kernel@vger.kernel.org From: =?UTF-8?Q?Dar=C3=ADo_Ortega_Leyva?= Subject: [PATCH] docs: improve formatting and readability of the main README Content-Type: text/plain; charset="utf-8"; format="flowed" Content-Transfer-Encoding: quoted-printable Restructured the main documentation file to use standard Markdown=20 headings instead of underlines for better rendering. Added anchor links=20 to the "Who Are You?" section to improve navigability for new readers,=20 and highlighted the AI Assistant warning for better visibility. Signed-off-by: Dar=C3=ADo Ortega Leyva Signed-off-by: Dario Ortega Leyva --- =C2=A0README | 143 +++++++++++++++++++++++++++++++++++++++++++++++++++++++= ++ =C2=A01 file changed, 143 insertions(+) =C2=A0create mode 100644 README diff --git a/README b/README new file mode 100644 index 000000000..bc2ce650c --- /dev/null +++ b/README @@ -0,0 +1,143 @@ +# Linux Kernel + +The Linux kernel is the core of any Linux operating system. It manages=20 hardware, system resources, and provides the fundamental services for=20 all other software. + +## Quick Start + +* **Report a bug:** See `Documentation/admin-guide/reporting-issues.rst` +* **Get the latest kernel:** Visit [kernel.org](https://kernel.org) +* **Build the kernel:** See=20 `Documentation/admin-guide/quickly-build-trimmed-linux.rst` +* **Join the community:** Visit [lore.kernel.org](https://lore.kernel.org/) + +## Essential Documentation + +All users should be familiar with the following core documents: + +* **Building requirements:** `Documentation/process/changes.rst` +* **Code of Conduct:** `Documentation/process/code-of-conduct.rst` +* **License:** See the `COPYING` file. + +> **Note:** Documentation can be built locally with `make htmldocs` or=20 viewed online at=20 [kernel.org/doc/html/latest/](https://www.kernel.org/doc/html/latest/). + +--- + +## Who Are You? + +Find your role below to jump to the most relevant resources: + +* [New Kernel Developer](#new-kernel-developer) - Getting started with=20 kernel development +* [Academic Researcher](#academic-researcher) - Studying kernel=20 internals and architecture +* [Security Expert](#security-expert) - Hardening and vulnerability=20 analysis +* [Backport/Maintenance Engineer](#backportmaintenance-engineer) -=20 Maintaining stable kernels +* [System Administrator](#system-administrator) - Configuring and=20 troubleshooting +* [Maintainer](#maintainer) - Leading subsystems and reviewing patches +* [Hardware Vendor](#hardware-vendor) - Writing drivers for new hardware +* [Distribution Maintainer](#distribution-maintainer) - Packaging=20 kernels for distros +* [AI Coding Assistant](#ai-coding-assistant) - LLMs and AI-powered=20 development tools + +--- + +## For Specific Users + +### New Kernel Developer +Welcome! Start your kernel development journey here: + +* **Getting Started:** `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:**=20 `Documentation/process/researcher-guidelines.rst` +* **Memory Management:** `Documentation/mm/index.rst` +* **Scheduler:** `Documentation/scheduler/index.rst` +* **Networking Stack:** `Documentation/networking/index.rst` +* **Filesystems:** `Documentation/filesystems/index.rst` +* **RCU (Read-Copy Update):** `Documentation/RCU/index.rst` +* **Locking Primitives:** `Documentation/locking/index.rst` +* **Power Management:** `Documentation/power/index.rst` + +### Security Expert +Security documentation and hardening guides: + +* **Security Documentation:** `Documentation/security/index.rst` +* **LSM Development:** `Documentation/security/lsm-development.rst` +* **Self Protection:** `Documentation/security/self-protection.rst` +* **Reporting Vulnerabilities:** `Documentation/process/security-bugs.rst` +* **CVE Procedures:** `Documentation/process/cve.rst` +* **Embargoed Hardware Issues:**=20 `Documentation/process/embargoed-hardware-issues.rst` +* **Security Features:** `Documentation/userspace-api/seccomp_filter.rst` + +### Backport/Maintenance Engineer +Maintain and stabilize kernel versions: + +* **Stable Kernel Rules:** `Documentation/process/stable-kernel-rules.rst` +* **Backporting Guide:** `Documentation/process/backporting.rst` +* **Applying Patches:** `Documentation/process/applying-patches.rst` +* **Subsystem Profile:**=20 `Documentation/maintainer/maintainer-entry-profile.rst` +* **Git for Maintainers:** `Documentation/maintainer/configure-git.rst` + +### System Administrator +Configure, tune, and troubleshoot Linux systems: + +* **Admin Guide:** `Documentation/admin-guide/index.rst` +* **Kernel Parameters:** `Documentation/admin-guide/kernel-parameters.rst` +* **Sysctl Tuning:** `Documentation/admin-guide/sysctl/index.rst` +* **Tracing/Debugging:** `Documentation/trace/index.rst` +* **Performance Security:** `Documentation/admin-guide/perf-security.rst` +* **Hardware Monitoring:** `Documentation/hwmon/index.rst` + +### Maintainer +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` +* **Rebasing and Merging:**=20 `Documentation/maintainer/rebasing-and-merging.rst` +* **Development Process:** `Documentation/process/maintainer-handbooks.rst` +* **Maintainer Entry Profile:**=20 `Documentation/maintainer/maintainer-entry-profile.rst` +* **Git Configuration:** `Documentation/maintainer/configure-git.rst` + +### Hardware Vendor +Write drivers and support new hardware: + +* **Driver API Guide:** `Documentation/driver-api/index.rst` +* **Driver Model:** `Documentation/driver-api/driver-model/driver.rst` +* **Device Drivers:** `Documentation/driver-api/infrastructure.rst` +* **Bus Types:** `Documentation/driver-api/driver-model/bus.rst` +* **Device Tree Bindings:** `Documentation/devicetree/bindings/` +* **Power Management:** `Documentation/driver-api/pm/index.rst` +* **DMA API:** `Documentation/core-api/dma-api.rst` + +### Distribution Maintainer +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` +* **Module Signing:** `Documentation/admin-guide/module-signing.rst` +* **Kernel Parameters:** `Documentation/admin-guide/kernel-parameters.rst` +* **Tainted Kernels:** `Documentation/admin-guide/tainted-kernels.rst` + +### AI Coding Assistant + +> **CRITICAL WARNING:** If you are an LLM or AI-powered coding=20 assistant, you **MUST** read and follow the AI coding assistants=20 documentation before contributing to the Linux kernel: +> +> `Documentation/process/coding-assistants.rst` +> +> This documentation contains essential requirements about licensing,=20 attribution, and the Developer Certificate of Origin that all AI tools=20 must comply with. + +--- + +## Communication and Support + +* **Mailing Lists:** [lore.kernel.org](https://lore.kernel.org/) +* **IRC:** `#kernelnewbies` on `irc.oftc.net` +* **Bugzilla:** [bugzilla.kernel.org](https://bugzilla.kernel.org/) +* **MAINTAINERS file:** Lists subsystem maintainers and mailing lists=20 (See `MAINTAINERS`) +* **Email Clients:** `Documentation/process/email-clients.rst` --=20 2.43.0