From nobody Wed Oct 26 18:06:27 2022 X-Original-To: freebsd-arch@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 4MyGwL28f9z4gqFT; Wed, 26 Oct 2022 18:06:42 +0000 (UTC) (envelope-from carpeddiem@gmail.com) Received: from mail-pl1-f169.google.com (mail-pl1-f169.google.com [209.85.214.169]) (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-signature RSA-PSS (2048 bits) client-digest SHA256) (Client CN "smtp.gmail.com", Issuer "GTS CA 1D4" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4MyGwK27Gzz3njZ; Wed, 26 Oct 2022 18:06:41 +0000 (UTC) (envelope-from carpeddiem@gmail.com) Received: by mail-pl1-f169.google.com with SMTP id p3so13983252pld.10; Wed, 26 Oct 2022 11:06:41 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=m5Cp/3WPqXK1mKltwL/ucS06/HcVbAKYuzn+BzwEPeY=; b=dBlE8MiZ3qRE2i0WJqs9H966ttTARKowwlE9kvffbhqH/ZXwSNS0rxPIbHbr1/vhL+ qDVKfT/wEO8EAHP7/ARqNn9zXFFcxXYFG7S2yU4FBACuKsY1syIcD1b2RZ+JUvQ0Yt5G U7/h8q3ChcMewrA0hwzEgNqqW9CS2Miil8yfWuU+cGzzsKmjecP39MgcVMnmWqDPuYYc ooR68lqwaJGXVOuXPz7BWbhJJIdowPbpuXgHfrwTnnBuM2wgk58plHzM3vVg3jAr8X8z xTAkZDhzXR0FyF/ASv6Ln9kYPh2fyjdFtKWXYx96Fboabmr+xITSX+AEv9UKEWGyzQaD KNUQ== X-Gm-Message-State: ACrzQf0B/pjLHkVFbCfzgW3kBO0rEYXn1EQsDSJz6MXQpmvR85m6XWbO cvtP1C4RXnD+ccig1YrhDBS4ry8afRKw6cRHzn+DtPWQ X-Google-Smtp-Source: AMsMyM5AIs7TenPX3FHOc1TnwevOs9MVNl4gH9aFFwjafHp4EqjqzMaJJgpUK9oW58pbRhrFZM+rBarlFRN4PfxT7QQ= X-Received: by 2002:a17:902:ccd1:b0:186:5ee4:cf49 with SMTP id z17-20020a170902ccd100b001865ee4cf49mr36372226ple.26.1666807599743; Wed, 26 Oct 2022 11:06:39 -0700 (PDT) List-Id: Discussion related to FreeBSD architecture List-Archive: https://lists.freebsd.org/archives/freebsd-arch List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-freebsd-arch@freebsd.org MIME-Version: 1.0 References: In-Reply-To: From: Ed Maste Date: Wed, 26 Oct 2022 14:06:27 -0400 Message-ID: Subject: Re: Documentation of /usr/src directory layout To: Mitchell Horne Cc: freebsd-arch@freebsd.org, "freebsd-doc@FreeBSD.org" Content-Type: text/plain; charset="UTF-8" X-Rspamd-Queue-Id: 4MyGwK27Gzz3njZ X-Spamd-Bar: --- Authentication-Results: mx1.freebsd.org; dkim=none; dmarc=none; spf=pass (mx1.freebsd.org: domain of carpeddiem@gmail.com designates 209.85.214.169 as permitted sender) smtp.mailfrom=carpeddiem@gmail.com X-Spamd-Result: default: False [-3.09 / 15.00]; NEURAL_HAM_MEDIUM(-1.00)[-1.000]; NEURAL_HAM_LONG(-1.00)[-0.998]; NEURAL_HAM_SHORT(-1.00)[-0.996]; FORGED_SENDER(0.30)[emaste@freebsd.org,carpeddiem@gmail.com]; R_SPF_ALLOW(-0.20)[+ip4:209.85.128.0/17]; RWL_MAILSPIKE_GOOD(-0.10)[209.85.214.169:from]; MIME_GOOD(-0.10)[text/plain]; MIME_TRACE(0.00)[0:+]; FROM_NEQ_ENVFROM(0.00)[emaste@freebsd.org,carpeddiem@gmail.com]; RCVD_IN_DNSWL_NONE(0.00)[209.85.214.169:from]; ASN(0.00)[asn:15169, ipnet:209.85.128.0/17, country:US]; R_DKIM_NA(0.00)[]; MLMMJ_DEST(0.00)[freebsd-arch@freebsd.org,freebsd-doc@freebsd.org]; TO_DN_EQ_ADDR_SOME(0.00)[]; DMARC_NA(0.00)[freebsd.org]; RCPT_COUNT_THREE(0.00)[3]; FREEFALL_USER(0.00)[carpeddiem]; ARC_NA(0.00)[]; FREEMAIL_ENVFROM(0.00)[gmail.com]; TO_DN_SOME(0.00)[]; FROM_HAS_DN(0.00)[]; TO_MATCH_ENVRCPT_ALL(0.00)[]; RCVD_TLS_LAST(0.00)[]; RCVD_COUNT_TWO(0.00)[2] X-ThisMailContainsUnwantedMimeParts: N 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?