Documentation of /usr/src directory layout
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
Re: Documentation of /usr/src directory layout
On Wed, 26 Oct 2022 at 12:07, Mitchell Horne wrote: > > 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]. Thanks Mitchell, overall I think this is a great idea. One question, is README.md the right place for this or should we add a CONTRIBUTING.md or similar?
Re: Documentation of /usr/src directory layout
On 10/26/22 15:06, Ed Maste wrote: On Wed, 26 Oct 2022 at 12:07, Mitchell Horne wrote: 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]. Thanks Mitchell, overall I think this is a great idea. One question, is README.md the right place for this or should we add a CONTRIBUTING.md or similar? IMO, it is appropriate to keep this in README.md, if for no other reason than the file is quite small -- 42 lines after my changes, including the table. But I consider it analogous to having a map displayed at a park entrance, or a table of contents at the start of a book.
Re: Documentation of /usr/src directory layout
On 2022-10-26 14:41, Mitchell Horne wrote: On 10/26/22 15:06, Ed Maste wrote: On Wed, 26 Oct 2022 at 12:07, Mitchell Horne wrote: 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]. Thanks Mitchell, overall I think this is a great idea. One question, is README.md the right place for this or should we add a CONTRIBUTING.md or similar? IMO, it is appropriate to keep this in README.md, if for no other reason than the file is quite small -- 42 lines after my changes, including the table. But I consider it analogous to having a map displayed at a park entrance, or a table of contents at the start of a book. I agree README.md is best, it is what tools like gitlab and github show by default, so again to Mitchell's point, it is the most discoverable location. -- Allan Jude
Re: Documentation of /usr/src directory layout
On 2022-10-26 16:07, Mitchell Horne wrote: 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. Noting that (on 13.1 at least) README.md is a lightly markdownized version of README. If they're not going to be kept consistent going forward, one should be removed. (As mentioned elsethread, keeping README.md makes sense given GitHub and others display it by default.) Re removing that info from hier(7) instead of updating it, a possible disadvantage I see to that is people without source losing access to it. I'm not familiar with the audience: how likely is it that people without source installed will have a need for (a more current version of) that part of it? -- #BlackLivesMatter #TransWomenAreWomen #AccessibilityMatters #StandWithUkrainians English: he/him/his (singular they/them/their/theirs OK) French: il/le/lui (iel/iel and ielle/ielle OK) Tagalog: siya/niya/kaniya (please avoid sila/nila/kanila)
