From nobody Thu Oct 27 01:30:41 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 4MySmn0XYcz4gfMM for ; Thu, 27 Oct 2022 01:30:49 +0000 (UTC) (envelope-from allanjude@freebsd.org) Received: from tor1-11.mx.scaleengine.net (tor1-11.mx.scaleengine.net [IPv6:2001:470:1:474::25]) (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 did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 4MySml643Pz3Gvd for ; Thu, 27 Oct 2022 01:30:47 +0000 (UTC) (envelope-from allanjude@freebsd.org) Received: from [10.1.1.110] (unknown [10.2.89.2]) (Authenticated sender: allanjude.freebsd@scaleengine.com) by tor1-11.mx.scaleengine.net (Postfix) with ESMTPSA id 61A5932AA8 for ; Thu, 27 Oct 2022 01:30:41 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.10.3 tor1-11.mx.scaleengine.net 61A5932AA8 Message-ID: <718215e8-81cb-75e0-dcd5-9e41dd89ff11@freebsd.org> Date: Wed, 26 Oct 2022 21:30:41 -0400 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 (Windows NT 10.0; Win64; x64; rv:102.0) Gecko/20100101 Thunderbird/102.4.0 Subject: Re: Documentation of /usr/src directory layout Content-Language: en-US To: freebsd-doc@freebsd.org References: <1e1fce17-5953-9fc3-e1c4-59bbf5086e0c@freebsd.org> From: Allan Jude In-Reply-To: <1e1fce17-5953-9fc3-e1c4-59bbf5086e0c@freebsd.org> Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit X-Rspamd-Queue-Id: 4MySml643Pz3Gvd X-Spamd-Bar: --- Authentication-Results: mx1.freebsd.org; dkim=none; dmarc=none; spf=softfail (mx1.freebsd.org: 2001:470:1:474::25 is neither permitted nor denied by domain of allanjude@freebsd.org) smtp.mailfrom=allanjude@freebsd.org X-Spamd-Result: default: False [-3.10 / 15.00]; NEURAL_HAM_LONG(-1.00)[-1.000]; NEURAL_HAM_MEDIUM(-1.00)[-1.000]; NEURAL_HAM_SHORT(-1.00)[-1.000]; MIME_GOOD(-0.10)[text/plain]; MLMMJ_DEST(0.00)[freebsd-doc@freebsd.org]; DMARC_NA(0.00)[freebsd.org]; FROM_EQ_ENVFROM(0.00)[]; MIME_TRACE(0.00)[0:+]; R_DKIM_NA(0.00)[]; RCVD_COUNT_TWO(0.00)[2]; ASN(0.00)[asn:6939, ipnet:2001:470::/32, country:US]; RCVD_TLS_ALL(0.00)[]; ARC_NA(0.00)[]; R_SPF_SOFTFAIL(0.00)[~all:c]; FROM_HAS_DN(0.00)[]; FREEFALL_USER(0.00)[allanjude]; RCVD_VIA_SMTP_AUTH(0.00)[]; RCPT_COUNT_ONE(0.00)[1]; TO_MATCH_ENVRCPT_ALL(0.00)[]; PREVIOUSLY_DELIVERED(0.00)[freebsd-doc@freebsd.org]; MID_RHS_MATCH_FROM(0.00)[]; TO_DN_NONE(0.00)[]; TO_DOM_EQ_FROM_DOM(0.00)[] X-ThisMailContainsUnwantedMimeParts: N 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