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 <mhorne@freebsd.org> 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