Skip to content

Commit b9a565b

Browse files
Sasha LevinJonathan Corbet
Sasha Levin
authored and
Jonathan Corbet
committed
README: restructure with role-based documentation and guidelines
Reorganize README to provide targeted documentation paths for different user roles including developers, researchers, security experts, and maintainers. Add quick start section and essential docs links. Signed-off-by: Sasha Levin <sashal@kernel.org> Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Reviewed-by: Kees Cook <kees@kernel.org> Reviewed-by: SeongJae Park <sj@kernel.org> Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <20251121180009.2634393-1-sashal@kernel.org>
1 parent 5f88f44 commit b9a565b

1 file changed

Lines changed: 149 additions & 11 deletions

File tree

‎README‎

Lines changed: 149 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,156 @@
11
Linux kernel
22
============
33

4-
There are several guides for kernel developers and users. These guides can
5-
be rendered in a number of formats, like HTML and PDF. Please read
6-
Documentation/admin-guide/README.rst first.
4+
The Linux kernel is the core of any Linux operating system. It manages hardware,
5+
system resources, and provides the fundamental services for all other software.
76

8-
In order to build the documentation, use ``make htmldocs`` or
9-
``make pdfdocs``. The formatted documentation can also be read online at:
7+
Quick Start
8+
-----------
109

11-
https://www.kernel.org/doc/html/latest/
10+
* Report a bug: See Documentation/admin-guide/reporting-issues.rst
11+
* Get the latest kernel: https://kernel.org
12+
* Build the kernel: See Documentation/admin-guide/quickly-build-trimmed-linux.rst
13+
* Join the community: https://lore.kernel.org/
1214

13-
There are various text files in the Documentation/ subdirectory,
14-
several of them using the reStructuredText markup notation.
15+
Essential Documentation
16+
-----------------------
1517

16-
Please read the Documentation/process/changes.rst file, as it contains the
17-
requirements for building and running the kernel, and information about
18-
the problems which may result by upgrading your kernel.
18+
All users should be familiar with:
19+
20+
* Building requirements: Documentation/process/changes.rst
21+
* Code of Conduct: Documentation/process/code-of-conduct.rst
22+
* License: See COPYING
23+
24+
Documentation can be built with make htmldocs or viewed online at:
25+
https://www.kernel.org/doc/html/latest/
26+
27+
28+
Who Are You?
29+
============
30+
31+
Find your role below:
32+
33+
* New Kernel Developer - Getting started with kernel development
34+
* Academic Researcher - Studying kernel internals and architecture
35+
* Security Expert - Hardening and vulnerability analysis
36+
* Backport/Maintenance Engineer - Maintaining stable kernels
37+
* System Administrator - Configuring and troubleshooting
38+
* Maintainer - Leading subsystems and reviewing patches
39+
* Hardware Vendor - Writing drivers for new hardware
40+
* Distribution Maintainer - Packaging kernels for distros
41+
42+
43+
For Specific Users
44+
==================
45+
46+
New Kernel Developer
47+
--------------------
48+
49+
Welcome! Start your kernel development journey here:
50+
51+
* Getting Started: Documentation/process/development-process.rst
52+
* Your First Patch: Documentation/process/submitting-patches.rst
53+
* Coding Style: Documentation/process/coding-style.rst
54+
* Build System: Documentation/kbuild/index.rst
55+
* Development Tools: Documentation/dev-tools/index.rst
56+
* Kernel Hacking Guide: Documentation/kernel-hacking/hacking.rst
57+
* Core APIs: Documentation/core-api/index.rst
58+
59+
Academic Researcher
60+
-------------------
61+
62+
Explore the kernel's architecture and internals:
63+
64+
* Researcher Guidelines: Documentation/process/researcher-guidelines.rst
65+
* Memory Management: Documentation/mm/index.rst
66+
* Scheduler: Documentation/scheduler/index.rst
67+
* Networking Stack: Documentation/networking/index.rst
68+
* Filesystems: Documentation/filesystems/index.rst
69+
* RCU (Read-Copy Update): Documentation/RCU/index.rst
70+
* Locking Primitives: Documentation/locking/index.rst
71+
* Power Management: Documentation/power/index.rst
72+
73+
Security Expert
74+
---------------
75+
76+
Security documentation and hardening guides:
77+
78+
* Security Documentation: Documentation/security/index.rst
79+
* LSM Development: Documentation/security/lsm-development.rst
80+
* Self Protection: Documentation/security/self-protection.rst
81+
* Reporting Vulnerabilities: Documentation/process/security-bugs.rst
82+
* CVE Procedures: Documentation/process/cve.rst
83+
* Embargoed Hardware Issues: Documentation/process/embargoed-hardware-issues.rst
84+
* Security Features: Documentation/userspace-api/seccomp_filter.rst
85+
86+
Backport/Maintenance Engineer
87+
-----------------------------
88+
89+
Maintain and stabilize kernel versions:
90+
91+
* Stable Kernel Rules: Documentation/process/stable-kernel-rules.rst
92+
* Backporting Guide: Documentation/process/backporting.rst
93+
* Applying Patches: Documentation/process/applying-patches.rst
94+
* Subsystem Profile: Documentation/maintainer/maintainer-entry-profile.rst
95+
* Git for Maintainers: Documentation/maintainer/configure-git.rst
96+
97+
System Administrator
98+
--------------------
99+
100+
Configure, tune, and troubleshoot Linux systems:
101+
102+
* Admin Guide: Documentation/admin-guide/index.rst
103+
* Kernel Parameters: Documentation/admin-guide/kernel-parameters.rst
104+
* Sysctl Tuning: Documentation/admin-guide/sysctl/index.rst
105+
* Tracing/Debugging: Documentation/trace/index.rst
106+
* Performance Security: Documentation/admin-guide/perf-security.rst
107+
* Hardware Monitoring: Documentation/hwmon/index.rst
108+
109+
Maintainer
110+
----------
111+
112+
Lead kernel subsystems and manage contributions:
113+
114+
* Maintainer Handbook: Documentation/maintainer/index.rst
115+
* Pull Requests: Documentation/maintainer/pull-requests.rst
116+
* Managing Patches: Documentation/maintainer/modifying-patches.rst
117+
* Rebasing and Merging: Documentation/maintainer/rebasing-and-merging.rst
118+
* Development Process: Documentation/process/maintainer-handbooks.rst
119+
* Maintainer Entry Profile: Documentation/maintainer/maintainer-entry-profile.rst
120+
* Git Configuration: Documentation/maintainer/configure-git.rst
121+
122+
Hardware Vendor
123+
---------------
124+
125+
Write drivers and support new hardware:
126+
127+
* Driver API Guide: Documentation/driver-api/index.rst
128+
* Driver Model: Documentation/driver-api/driver-model/driver.rst
129+
* Device Drivers: Documentation/driver-api/infrastructure.rst
130+
* Bus Types: Documentation/driver-api/driver-model/bus.rst
131+
* Device Tree Bindings: Documentation/devicetree/bindings/
132+
* Power Management: Documentation/driver-api/pm/index.rst
133+
* DMA API: Documentation/core-api/dma-api.rst
134+
135+
Distribution Maintainer
136+
-----------------------
137+
138+
Package and distribute the kernel:
139+
140+
* Stable Kernel Rules: Documentation/process/stable-kernel-rules.rst
141+
* ABI Documentation: Documentation/ABI/README
142+
* Kernel Configuration: Documentation/kbuild/kconfig.rst
143+
* Module Signing: Documentation/admin-guide/module-signing.rst
144+
* Kernel Parameters: Documentation/admin-guide/kernel-parameters.rst
145+
* Tainted Kernels: Documentation/admin-guide/tainted-kernels.rst
146+
147+
148+
149+
Communication and Support
150+
=========================
151+
152+
* Mailing Lists: https://lore.kernel.org/
153+
* IRC: #kernelnewbies on irc.oftc.net
154+
* Bugzilla: https://bugzilla.kernel.org/
155+
* MAINTAINERS file: Lists subsystem maintainers and mailing lists
156+
* Email Clients: Documentation/process/email-clients.rst

0 commit comments

Comments
 (0)