Hello,
Currently, hier(7) contains detailed but outdated [1] documentation of
the directory structure under /usr/src. The src tree's README.md file
duplicates much of this information by maintaining a distinctly
incomplete table.
I propose that we reduce the maintenance overhead by keeping one of
these lists as the source of truth. README.md is the more natural option
here: being located at the root of the src tree it is more discoverable
(especially for those new to the src tree), and the raw markdown text is
much more human-readable than mdoc. Of course, the added benefit is that
README.md is presented front-and-center when browsing the git repository
on GitHub, GitLab, etc. See it on my fork [2].
The list of /usr/src subdirectories will be removed from hier(7) and
replaced with a sentence informing the reader they can consult README.md
for the details.
I have retained and improved the list of directories under sys/ from
hier(7), but to avoid polluting the top-level source roadmap I have
added a secondary sys/README.md which documents the layout of the kernel
sources.
I do not expect these changes to be contentious, but I'd like to cast a
wider net for review. Productive feedback is welcome by email or
directly in the Phabricator reviews:
https://reviews.freebsd.org/D37132
https://reviews.freebsd.org/D37133
https://reviews.freebsd.org/D37134
https://reviews.freebsd.org/D37135
https://reviews.freebsd.org/D37136
Also, this information is duplicated in at least one more place: the
Developer's Handbook [3]. I intend to address this too after the current
series of changes is complete. Most likely, this will be done by
replacing the list with a link to the README.md file in cgit.
Thanks!
Mitchell
[1] https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=261349
[2] https://github.com/mhorne/freebsd/tree/hier
[3]
https://docs.freebsd.org/en/books/developers-handbook/introduction/#introduction-layout
