linux-kernel - Re: [PATCH] Documentation: Add a source tree map overview

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] [thread-next>] [day] [month] [year] [list]

Message-ID: <f882f6d9-c914-48af-97b7-0aad6d995819@infradead.org>
Date: Sun, 1 Jun 2025 09:50:14 -0700
From: Randy Dunlap <rdunlap@...radead.org>
To: William Raezer <wraezer@...il.com>, linux-doc@...r.kernel.org
Cc: linux-kernel@...r.kernel.org, corbet@....net
Subject: Re: [PATCH] Documentation: Add a source tree map overview

Hi,

On 6/1/25 9:22 AM, William Raezer wrote:
> Hello,
> 

Please wrap email lines at around 72-75 characters each.

> My name is William Raezer, and this is my first contribution to the Linux kernel. I'm submitting a simple but hopefully helpful addition: a high-level map of the Linux kernel source tree as a new document in `Documentation/source-map.rst`.

This looks somewhat useful, although I was expecting more of a graphic presentation
of the tree structure. But that would cause trouble with the role of each subdirectory.
(and one can always use `tree` for that)

> As someone beginning to explore the internals of the Linux kernel, I noticed that while there is some documentation available that describes the subsystems in principle, there's no centralized overview of the source tree structure itself. This patch adds a basic source map that describes the role of each top-level directory in the kernel source.
> 
> The goal is to assist both myself and others in navigating the codebase, especially new contributors who may be overwhelmed by the kernel's size and complexity. As a follow-up, I plan to add subsystem-level maps for key directories such as `kernel/`, `mm/`, and `fs/`.
> 
> I hope this addition is seen as a positive and useful step, and I’m open to feedback or suggestions to improve it.

Patches should generally be inline as email text, not as attachments.
This is up to the maintainer to decide about...
and gmail is not good as maintaining whitespace in emails.
(I don't see any whitespace problems in the current patch.)

I get a warning when building with this patch applied:

Documentation/source-map.rst: WARNING: document isn't included in any toctree [toc.not_included]

Also, when I look at source-map.html with a web browser, no parts of
the source-map are shown. (tested with multiple browsers)

Thanks.
-- 
~Randy