From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp11.migadu.com ([2001:41d0:403:478a::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms9.migadu.com with LMTPS id KJjEJazM+GTG8wAA9RJhRA:P1 (envelope-from ) for ; Wed, 06 Sep 2023 21:02:04 +0200 Received: from aspmx1.migadu.com ([2001:41d0:403:478a::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp11.migadu.com with LMTPS id KJjEJazM+GTG8wAA9RJhRA (envelope-from ) for ; Wed, 06 Sep 2023 21:02:04 +0200 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id 5553756BDC for ; Wed, 6 Sep 2023 21:02:04 +0200 (CEST) Authentication-Results: aspmx1.migadu.com; dkim=none; spf=pass (aspmx1.migadu.com: domain of "guix-devel-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-devel-bounces+larch=yhetil.org@gnu.org"; dmarc=none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1694026924; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type:in-reply-to:in-reply-to: references:references:list-id:list-help:list-unsubscribe: list-subscribe:list-post; bh=hq0Kk58UDL4sQjQTl070Ju1ahofN7NNtEmFc7XNm9a8=; b=iBLx8Om0KBmyq8tFCx1raeYXiFS1TeGs1BFo1RROXBMU6WTJF6vln5rQXZxKxLDhr4aJXX nYYh7QetJCoVYITj7+q+AlQfUwXh+3QTjRaFW3RDdNHC+phawXjqNSKzfcqo4MkoVuch2m 5t+WvpdXlQQt2PPozKTJymv4YoBMmAYs21OB7uUN3ipDS6JQ80+d0iIZYPBHd0OxVI63gW c5xNsnjOJJsBTcUy1vd58jC8j6h2aFaDVciZo1FedW4RBMxWJwbkceXvTipWNZ/ixw8hEC uuZJmd3Txt8/kFTZz7RI6DI5m6CUtYEp/Ox2F9xSUfLCs7AzZ3bq6YQq+TSGjA== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1694026924; a=rsa-sha256; cv=none; b=i1Zw19cQLNSS9PBRlo2gntqgfhNh9y6AlFumQsUPXXPHcyfDuylmcKUEyt05YcH1R9xcp2 /UHZMiEGvZTYifR1mpEvPmTcSx9wM+IJwNw1cmIKk9yT9EvY1gU6eSoUD4stokrMXBTqcN 1rFyRSztnkl/HUFnQm3Y4HRcvA4UcAbRYw030AQDFy/hyl9fD1imo4zwRNxcEWIaCal2TQ nkPcUvnuvMmjnMubnWuYQ0FIE8TnUnZxBv6JgQGV9pDv24LtGyKXq8MLoTez7PYwOy9KMu smqppzLqqWbcBLg+2Rds5vqWYOR8LNfsgpkScywJ+6GraPymYWsLQbym65SBwA== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=none; spf=pass (aspmx1.migadu.com: domain of "guix-devel-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-devel-bounces+larch=yhetil.org@gnu.org"; dmarc=none Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qdxmT-0005t2-Nx; Wed, 06 Sep 2023 15:01:37 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qdxmR-0005sa-R1 for guix-devel@gnu.org; Wed, 06 Sep 2023 15:01:35 -0400 Received: from mira.cbaines.net ([212.71.252.8]) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qdxmP-00086f-42 for guix-devel@gnu.org; Wed, 06 Sep 2023 15:01:35 -0400 Received: from localhost (unknown [217.155.61.229]) by mira.cbaines.net (Postfix) with ESMTPSA id BFC2627BBE2; Wed, 6 Sep 2023 20:01:31 +0100 (BST) Received: from felis (localhost [127.0.0.1]) by localhost (OpenSMTPD) with ESMTP id dbaf5026; Wed, 6 Sep 2023 19:01:31 +0000 (UTC) References: <20230827135726.y33t55w4cvq6zsvb@X-kone> <874jkift8v.fsf@gmail.com> <867cp4sj7k.fsf@gmail.com> <38242808-2f06-4674-3842-aea1a5378d05@gmail.com> <87a5u0o3z2.fsf@disroot.org> <87sf7s9oi9.fsf@spork.org> <67115f26712acbb1d83b71f4418c682a5e9762a4.camel@gmail.com> <87h6o7mbo2.fsf@wireframe> <87sf7rqhqw.fsf@gmail.com> User-agent: mu4e 1.10.5; emacs 28.2 From: Christopher Baines To: Maxim Cournoyer Cc: Vagrant Cascadian , guix-devel@gnu.org Subject: Re: How can we decrease the cognitive overhead for contributors? Date: Wed, 06 Sep 2023 19:49:33 +0100 In-reply-to: <87sf7rqhqw.fsf@gmail.com> Message-ID: <87fs3razxy.fsf@cbaines.net> MIME-Version: 1.0 Content-Type: multipart/signed; boundary="=-=-="; micalg=pgp-sha512; protocol="application/pgp-signature" Received-SPF: pass client-ip=212.71.252.8; envelope-from=mail@cbaines.net; helo=mira.cbaines.net X-Spam_score_int: -18 X-Spam_score: -1.9 X-Spam_bar: - X-Spam_report: (-1.9 / 5.0 requ) BAYES_00=-1.9, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: guix-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-devel-bounces+larch=yhetil.org@gnu.org Sender: guix-devel-bounces+larch=yhetil.org@gnu.org X-Migadu-Country: US X-Migadu-Flow: FLOW_IN X-Migadu-Scanner: mx0.migadu.com X-Migadu-Spam-Score: -7.33 X-Spam-Score: -7.33 X-Migadu-Queue-Id: 5553756BDC X-TUID: OL421hmXAzzU --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Maxim Cournoyer writes: > Hi Vagrant, > > Vagrant Cascadian writes: > >> On 2023-09-06, Liliana Marie Prikler wrote: >>> Am Dienstag, dem 05.09.2023 um 19:41 -0400 schrieb brian >>>> =E2=80=98* foo/bar.scm new-package (inputs): add input=E2=80=99 >>>>=20 >>>> stuff. I literally can never remember this format, no matter how many >>>> times I do it. I'm reasonably sure square brackes go in there some >>>> where. It can take me quite a while to put together all that stuff, >>>> even with magit's help. >>> It's=20 >>> >>> * file (variable)[field]{do you need 4 levels?} >> >> Honestly, not knowing the difference between a variable and field and >> selector... this comment is of little help to me. >> >> I always get tripped up with phases, modify-phases, etc. as there seem >> to be potentially four or more levels deep in some common code >> patterns... for example, a recent commit mentioning phases: > > The ChangeLog Style section suggests there should be spaces between the > "markers". It also says the square brackets should be used to denote a > change made in a conditional code path, so we're abusing the meaning of > it in Guix to just a 'field' (which is, a record field, or slot, for the > record in Guix). < > is to precise even more the place > modified. They're just shortcuts to avoid less typing while remaining > readable. > > Here's an example in the Guix "dialect": > > * gnu/packages/file.scm (package-symbol) > [arguments] <#:phases>: New patch-paths phase. > > > It could also have been: > > * gnu/packages/file.scm (package-symbol) [arguments]: Add patch-paths > phase. > > It doesn't really matter, as long as it's clear and you did the exercise > of reviewing the code you touched and writing down the changes summary > for the reviewer (and yourself). I think I have a similar feeling to Vagrant, and on whether this matters, I think it matters a lot. In terms of encouraging people to contribute to Guix, we want the documentation to set people up for success, or at least feeling like they're doing things correctly. The docs say: Please write commit logs in the ChangeLog format (see Change Logs in GNU Coding Standards); you can check the commit history for examples. Which is expecting a lot of people who haven't encountered this before. My view on this is that asking people to perform this task that isn't very well documented or defined, and which people reviewing and committing the changes will comment on or revise (maybe to be objectively better, or maybe just in their own style) discourages people to continue to contribute, especially those that care more about not making mistakes/getting things right, or that lack confidence. I'm indifferent about how we write the commit messages, I'm strongly in favour of the expectations being clear and documented so that if people new to the project want to attempt to write a good commit message, they're setup for success with good documentation, and if something they write can be improved, there should be some bit of documentation you can point them to. --=-=-= Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQKlBAEBCgCPFiEEPonu50WOcg2XVOCyXiijOwuE9XcFAmT4zIlfFIAAAAAALgAo aXNzdWVyLWZwckBub3RhdGlvbnMub3BlbnBncC5maWZ0aGhvcnNlbWFuLm5ldDNF ODlFRUU3NDU4RTcyMEQ5NzU0RTBCMjVFMjhBMzNCMEI4NEY1NzcRHG1haWxAY2Jh aW5lcy5uZXQACgkQXiijOwuE9XdVIRAAtWWx9/K57qc2QCEw9iS6igDm53IElZCX ownm0Q88ShV64H/SA7tPU6UOKuc9Z/bH6NX8qDNiwky9yVwbeleEOTkBb3OPIKYd N3ATXpE7bXhxrYqplVei3lEHxbVq2hObSNsBVS6SGT0tFdrflwvdYd4kx7a0Y3YM se2qYRqRlxjtzLaHmAIMr2kLhe//1hg62EXvxjKm9PjOdSQHuOTxr5mC6sWt5TPa 6yCT1iGAF/tE3voovmLi7KuGyw3o0XIg6zrbZA49rkGQK/qqlakMN60n71LgsR14 XpC6vPrBpUe0PiULGwnLDfCJJIiLpC8nWelGHa+XXyZq30tyHD5Lj0BZH81gWl7G qellJmKzmv+Phh/OZk+3cmlBGAqvu8m5Ra3sjmOsZJRN8299ERBRR7C7XqdrggNz ZsGM8p8CidwBblh3EJDPHqxfB8Y2ZN3Kl4dL7NMUU3xavFzznBOeitkBNrlv/uAy uzS0rm14xwhVKvuoGxCYCHRLA/QvdgjETi5lWRdwSuPGsZHozkmzfqk4z6K0rVjO ifW3o/0sdjfQn9e2I9FRGXtusmWAdbJHKy/OS4GHpeFhhmI5bkgKqa1eX/tle4T7 y8i+LAL6dh53TxYISWVSnjv2NrjtH21uG0gRJ69blSUuER6Twot+lDP97r2VeXRX TQH1EQfe0Hs= =koYN -----END PGP SIGNATURE----- --=-=-=--