Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
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>
authored by
Sasha Levin
and committed by
Jonathan Corbet
b9a565b3
5f88f44d
+149
-11
+149
-11
README
+149
-11
README
···
1
1
Linux kernel
2
2
============
3
3
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.
7
6
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
+
-----------
10
9
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/
12
14
13
-
There are various text files in the Documentation/ subdirectory,
14
-
several of them using the reStructuredText markup notation.
15
+
Essential Documentation
16
+
-----------------------
15
17
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