From nobody Wed Oct 26 18:41:40 2022 X-Original-To: freebsd-doc@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4MyHhj18Tyz4gvvc; Wed, 26 Oct 2022 18:41:41 +0000 (UTC) (envelope-from mhorne@freebsd.org) Received: from smtp.freebsd.org (smtp.freebsd.org [96.47.72.83]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "smtp.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4MyHhj0jfdz3sGR; Wed, 26 Oct 2022 18:41:41 +0000 (UTC) (envelope-from mhorne@freebsd.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1666809701; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=/7dIXsc3+qfTdUNvJvms+m5oVDICEuB9G+tElPyWOi4=; b=Nwl6pOYE9MRAonbJiFF44Mzj2vg4InUPtAWIOp8TpSovkF1datafPWtJB0C3KiBY0R+Yoc Aau9+TzG7oJRHsvkjXUN/FzoVjvGi3ZHdvV3av2iMMhp8qBC2Rw7hOWW+Zw1YoMQCeT4// ENjarWZOp9FqRR6AgGSwaznO2TxQTF/L5NTiQxpr/QGei1NRy9qE3ex45Cfs8OBp5AOswu JH1DbVMq4X8Krh/sGCuYrzuDe0deaqm3DSBb4+/iSCrSjzlJCiTDZfMBjko52dVLn7FFSy z+rsNbsvOydQP9MCzW3JS7+oCLtrAQuSru4i5kaY8N4PVdyOwTdfMN/S/m04aw== Received: from [192.168.1.151] (host-173-212-76-127.public.eastlink.ca [173.212.76.127]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) (Authenticated sender: mhorne) by smtp.freebsd.org (Postfix) with ESMTPSA id 4MyHhh5WgbzVBn; Wed, 26 Oct 2022 18:41:40 +0000 (UTC) (envelope-from mhorne@freebsd.org) Message-ID: <1e1fce17-5953-9fc3-e1c4-59bbf5086e0c@freebsd.org> Date: Wed, 26 Oct 2022 15:41:40 -0300 List-Id: Documentation project List-Archive: https://lists.freebsd.org/archives/freebsd-doc List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-freebsd-doc@freebsd.org MIME-Version: 1.0 User-Agent: Mozilla/5.0 (X11; FreeBSD amd64; rv:102.0) Gecko/20100101 Thunderbird/102.4.0 Subject: Re: Documentation of /usr/src directory layout Content-Language: en-CA To: Ed Maste Cc: freebsd-arch@freebsd.org, "freebsd-doc@FreeBSD.org" References: From: Mitchell Horne In-Reply-To: Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1666809701; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=/7dIXsc3+qfTdUNvJvms+m5oVDICEuB9G+tElPyWOi4=; b=BwoPe86qlUchlGCActRRNQGduDTOrfUP/wCbg2IVPywVIpJ98E8GwRV16P37mxpk7whdEM Zj/hIyflkgzvFQ9t9vaD1z96y6Fi5TElJgda6qiibuXqGBKrQ8OkIqSa6eYn2uyk9NEQCM MUxV7O2eBCfPLtUDae7Zrvc0t3A2xwpNPYymoJie/oQ3tuUXHTTRazsFwVfNNfjN141Lq6 N0+AXB7nJr3+WUSwiSiIXWD36TKkpnR1GHA+o/BGatAIJMbDTeE0XqAd4lswjaBdWDDAoU mh/1MEwKy/G/5bVcGtOlPS5ivFFz60crOjRQgE7eJDn+h3chXBjHjgT7wALkFw== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1666809701; a=rsa-sha256; cv=none; b=qS3rUxkU218UQFHbPgOEsTaYnLoaLO1StNUc2pZr5Wx54rIW1aX9IWEgY1I4cr5M++muNA Mm7nCY8HdhIoXv09vh6sOJc6FW9Af2UHUmE3IgJDJeWP7MgQNxb9TTku6F5X3rbod/R9Hw lerGy+VrhArwFw5xPtYPWAU88ffBgPhjkoQghGNXLbisOouzgXD41EQOXCNbT+5u2k47h5 kUDaKwqEJBaJ/UhdGY6L1XGcQhhmlkCPPzfcT03z9BpL9C5tKSLHGpdujB/QTmlq8t+jYF dhpnDBHrzLCOFCIUFQe6mV0YbkVdOEtjPYJ3GLI/gjgJav7UfxocUe0mc88Aog== ARC-Authentication-Results: i=1; mx1.freebsd.org; none X-ThisMailContainsUnwantedMimeParts: N 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.