From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp10.migadu.com ([2001:41d0:306:2d92::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms9.migadu.com with LMTPS id OPr/HcoZ82Q3XAEAG6o9tA:P1 (envelope-from ) for ; Sat, 02 Sep 2023 13:17:30 +0200 Received: from aspmx1.migadu.com ([2001:41d0:306:2d92::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp10.migadu.com with LMTPS id OPr/HcoZ82Q3XAEAG6o9tA (envelope-from ) for ; Sat, 02 Sep 2023 13:17:30 +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 E81985B527 for ; Sat, 2 Sep 2023 13:17:29 +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=1693653450; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to: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=mOCfOWHr/Ex0/6NTw3evUwUJ3hvT90ZEQfvO6nDH+Vg=; b=O9S/+JJaZZpdezVCF2GhAmCza7hMWk2tltLXd31eYp2n3iU68TOxIbNBohJwmeT6FXeUC3 wDi8n1RjHguMAsGqTo5iWDPGA3hv2eFn+t16n79g5/DN5Td45LIsjOQ6JL8DDb9qOpDXWG 6RJLON6e7TwL2G+KGnlu8/wIdl5dnyGVesuewEStAGlmEn3TF7AKZKKYkOCov+4M6SxudJ dUdusxPySQw/iaudLaGaLPBYHy36EYtUVoN7xAsxp4CWs3YPO+5Sqer1iAnwgnli+yTHDC ZJuBXWoXCZNiz+qeCJDwDYRUaCe1vAXUPsQUYCeTJ+BZNlCnepUUaavlq7Ok2w== 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 ARC-Seal: i=1; s=key1; d=yhetil.org; t=1693653450; a=rsa-sha256; cv=none; b=uHNUIz7vmJ49K3jj/w0RhEuBsvRLNE3tGCILDyOCzcb1WaU+ndAQV6CoxW0C71YdnI9y/M BznUT5Ja6sMOLxfzcrXVdigKDpa6wVqYser0cWVNX83JuMOvMhIWaGgKXUfYHR3XTZEfy1 bH3HjB5nTJYapUTBYs+uzWmKQOKvL/nzfbAGi35LuCA7CxTDQ4Zg3FI5jgj6tT+Nkk1MJA Vaxn2UWd7Cx/d9zM71MP3jWdhxtCgeLueHNlKel6X9e1fJvxo8xn83C2mw+5aQ6ZWZg6Wu MKgqjjq+uRXF4LrYOfbdgfiNQ1b2wBcnGl1r8DGr9XKqbNIpXrXs/0nR3+OAfQ== Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qcOcc-00027D-4E; Sat, 02 Sep 2023 07:16:58 -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 1qcOca-00026r-Fb for guix-devel@gnu.org; Sat, 02 Sep 2023 07:16:56 -0400 Received: from ns13.heimat.it ([46.4.214.66]) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qcOcW-0006bB-D9 for guix-devel@gnu.org; Sat, 02 Sep 2023 07:16:56 -0400 Received: from localhost (ip6-localhost [127.0.0.1]) by ns13.heimat.it (Postfix) with ESMTP id 6E2E230022F; Sat, 2 Sep 2023 11:16:48 +0000 (UTC) X-Virus-Scanned: Debian amavisd-new at ns13.heimat.it Received: from ns13.heimat.it ([127.0.0.1]) by localhost (ns13.heimat.it [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id DARraFm1wlTx; Sat, 2 Sep 2023 11:16:45 +0000 (UTC) Received: from bourrache.mug.xelera.it (unknown [93.56.171.217]) (using TLSv1.2 with cipher ECDHE-ECDSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by ns13.heimat.it (Postfix) with ESMTPSA id CB33430022D; Sat, 2 Sep 2023 11:16:45 +0000 (UTC) Received: from roquette.mug.biscuolo.net (roquette [10.38.2.14]) by bourrache.mug.xelera.it (Postfix) with SMTP id 690E42964729; Sat, 2 Sep 2023 13:16:45 +0200 (CEST) Received: (nullmailer pid 7233 invoked by uid 1000); Sat, 02 Sep 2023 11:16:44 -0000 From: Giovanni Biscuolo To: Katherine Cox-Buday , guix-devel Subject: Re: How can we decrease the cognitive overhead for contributors? In-Reply-To: Organization: Xelera.eu References: <871qfsuvad.fsf@gmail.com> <8e74c4ac-a6f3-9127-7e13-593a2eb70432@gmail.com> <87a5ubqxm6.fsf@gmail.com> Date: Sat, 02 Sep 2023 13:16:44 +0200 Message-ID: <877cp8965f.fsf@xelera.eu> MIME-Version: 1.0 Content-Type: multipart/signed; boundary="=-=-="; micalg=pgp-sha512; protocol="application/pgp-signature" Received-SPF: pass client-ip=46.4.214.66; envelope-from=g@xelera.eu; helo=ns13.heimat.it 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_NONE=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-Spam-Score: -4.32 X-Spam-Score: -4.32 X-Migadu-Queue-Id: E81985B527 X-Migadu-Scanner: mx2.migadu.com X-TUID: Clvald1IBPbl --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Hello Katherine, thank you for having summarized (part of) this thread in a list of actionable tasks now Someone=E2=84=A2 have the chance to decrease the cognitive overhead for contributors by _increasing_ her cognitive overhead to sort out and complete each task as a general comment, it seems to me that you put very much attention to the process of contributing v1 of a patch but you underestimate the cognitive overhead of the collective patch reviewing process and committing to Guix proper process AFAIU, observing what is happening in Guix since 2019, what is actually critical for Guix is _not_ the cognitive overhead needed to send a patch to guix-devel, but what comes after and _around_. last but not least, to be fair we should see at what other distribution (not single software projects) are doing for their contributing process: I know a little about Debian and in my experience it's far easier to contribute to Guix than to Debian (but I know little, I emphasize) Katherine Cox-Buday writes: > Summary of my conclusions: > > 1. We should use sourcehut or continue to improve mumi Please forgive me if I insist, but the one and _only_ benefit of using SourceHut is the web-UI /helper/ to prepare an email message to send, it's "just" a web-UI version of the "git format-patch" CLI; the rest of the "patch management workflow" is email **and** CLI (git am) based; it's documented. Furthermore, users that are comfortable with the SourceHut web UI are free to use that as their personal working repo, there is no need for Guix to use a SourceHut remote as the official one. > =C2=A0=C2=A0 - QA status should be visable from a patch's page On mumi web interface, in each issue page related to a patch, there is a "badge" linking to the QA status for that patch, right below the issue title; i.e.: https://issues.guix.gnu.org/65694 have a link to https://qa.guix.gnu.org/issue/65694 QA (and relates services, like data.qa) is a great project that could greatly improve current situation when completed! > =C2=A0=C2=A0 - It should be possible to interact with the issue through = the > page I don't exactly understand: what do you mean with "interact"? ...and what page? https://issues.guix.gnu.org/ or https://qa.guix.gnu.org/issue/65694 (or any other issue) > 2. We should create scripts/sub-commands to lift contribution activities= =20 > into > =C2=A0=C2=A0 higher-order concepts: > =C2=A0=C2=A0 - Prepare a new submission > =C2=A0=C2=A0 - Run pre-checks on a submission > =C2=A0=C2=A0 - Submit a patch > =C2=A0=C2=A0 - Status of patch AFAIU you already use some of this "lifting" scripts od commands: can you please send patches so thay could possibly be included in Guix proper or in some section of the Cookbook? [...] > On 8/28/23 4:17 AM, Simon Tournier wrote: [...] > > In order to be pragmatical and list actionable items, could you > > specifically list what you consider as a toil or cognitive overhead? > > Maybe you could share your script helping you. > > Yes, great point! Let's try to distill all this conversation down into the > salient points and see if we can't agree on some actionable items. > > Here's my understanding of the process to contribute a patch: > > =C2=A0 1. Check out main, and run `./bootstrap`, then `./configure=20 > --localstatedir=3D/var --sysconfdir=3D/etc` > =C2=A0 2. Run `make` > =C2=A0 3. You need to determine whether the change can be targeted again= st=20 > main or > =C2=A0=C2=A0=C2=A0=C2=A0 needs to target a feature branch, so you go rea= d about that. [...] > In other projects I've worked with, steps 12-19 are commonly done in a CI > pipeline, and courteous people will try to save CI resources by running=20 > these > steps locally first using some kind of environment identical to what CI r= uns > (sometimes a container is used for this. I think Guix has better options!= ). > Sometimes this is not feasible due to asymmetric resources. But having the > option to let CI manage this process is very nice. AFAIU this is where https://qa.guix.gnu.org/ is intended to help, but now is not working as intended AFAIU > For me, steps 20-23 are bothersome. There's a lot of "if" statements=20 > that lead > to branching operations, and a lot of commands and flags to get > right. oh yes, CLI is a cognitive overhead sometimes, so we need better interfaces, some have found them actually, point 21 "Run `./pre-inst-env ./etc/teams.scm cc-members ` to get the CC flags for Git" is bothersome and we should find a way to better integrate that in "git format-patch" (so that will be automatically used in all the git interfaces we use) > The extra step to get a debbugs ID is annoying. have you tried mumi CLI with the new feature? > If I compare this workflow to the workflow of other contributions I make: > > =C2=A0 1-10 as usual > =C2=A0 11. Write a more commonly accepted commit message with no special= =20 > formatting. > =C2=A0 12. Run `git push` (subsequent changes are still just `git push`). > =C2=A0 13. Go to forge website, click button to open a pull-request. Forgive me if I insist: that forge site is _not_ SourceHut Second: each forge web site have a custom (not standard) way to manage pull-requests. Third: git have a pull-request mechanism [1] that could _easily_ be integrated in each and every forge, allowing projects to use /interoperable/ email based pull-request workflows if they want to. [...] > I don't find difficult, and reflected on the difference for awhile, I=20 > think, at > least for me, the highest friction comes from: > > - Steps 11-19, or (to assign it a name for easier reference) the "CI > steps". OK: AFAIU https://qa.guix.gnu.org/ is _the_ answer, so we need more contributors to that project ...and this means more cognitive overhead for Someone=E2=84=A2 :-) [...] > If we wanted to encourage contributors to run "CI steps"=20 > locally before > =C2=A0 submitting, maybe this should be another `guix` sub-command? `gui= x=20 > pre-check` > =C2=A0 or something? I know there is a potential contributor who had thi= s=20 > idea first > =C2=A0 who would want to hack on this. Having such a sub-command maybe could help, maybe not, because IMO the core and most cognitive challenging steps of all "CI steps" are not if builds are done locally or not but (in order of importance): 1. having patches reviewed by humans, the "not automatable" part because Someone=E2=84=A2 have to understand the _meaning_ of the patch and verify it conforms to the coding standards of the project, including "changelog style" commit messages; 2. understanding why build derivation fail when it fails. This is real cognitive overhead and this cannot be automated. > - Steps 19-23, or the "manage patch" steps. > > =C2=A0 I think an insight here is that the big button on forges is actua= lly=20 > a program > =C2=A0 removing the mental overhead for you. On the "web forges" vs "email based" patch workflow management I've said enough in other messages in this thread, here I just want to add (repeat) this: please do not only consider the mental overhead of potential contributors for "managing patches", also consider the mental overhead for patch reviewers; I've read many articles from professional patch reviewers that perfectly explains the great advanteges of using an email based workflow [...] > =C2=A0 I also don't usually have to worry nearly as much about crafting = a commit > =C2=A0 message. So long as the title is under a character limit, and the= body is > =C2=A0 helpful, it's OK. I think what bothers me most about the GNU chan= gelog > =C2=A0 messages is that it's the worst of both spoken language and progr= amming > =C2=A0 languages: there's an expectation of structure, but no grammar I = can=20 > parse > =C2=A0 against, and it's free-form. I'm sorry that the GNU policy about commit messages bothers you (on the contrary it makes me happy); please consider that thai is /just/ one of the policies of the Guix project: code of conduct, coding standards, others? [...] > - Having multiple places to manage aspects of my patch > > =C2=A0 In a web-forge, I generally have a URL I can go to and see everyt= hing=20 > about my > =C2=A0 patch. I think we have that with https://issues.guix.gnu.org with= two > =C2=A0 exceptions: (1) QA is a click away, or if you're using email, you= 're=20 > not even > =C2=A0 aware that there's a QA process failing (2) If you're not using e= mail, > =C2=A0 context-switching between this page and email to respond. it's "just" an _interface_ issue [...] Happy hacking! Gio' [1] https://www.git-scm.com/docs/git-request-pull =2D-=20 Giovanni Biscuolo Xelera IT Infrastructures --=-=-= Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQJABAEBCgAqFiEERcxjuFJYydVfNLI5030Op87MORIFAmTzGZwMHGdAeGVsZXJh LmV1AAoJENN9DqfOzDkSzr8P/3wkQj8px0KWjyZqDWfFWaNpR4j2oASJQFax2mGd VHRSoRqPv3oRpercSb+gnOa4tEhLIzspNReEwbQBWtsrW0OXQYz0bK1Wm4vXKcRW qrRXGZs57msOITcWJt+ymXtitNltQtzO47FymiPsitkmLYZ2ffb7AiUWrg8yn/jQ 8RoT+2B1DATkIM5oy4hF7GriWg02f5GTpfQmXZSLFlvq4f9ySrbYllbVXpz4Hmie MsEnxUeCFC7dvPFJDeGOtq8N7u8cXiHrhYgnyJc5tP6FaKw8DexMWHgkHd5Nr27J 3kV3wb20/cGc0pUhD5NQxHHORNqWCdFzUq0ZpF8bk1o1jpieiYAx8svXEVm5pvMH e1tZ3mMiplUoB89GMQrmh/hpmic8H+nhHRmwu0jbo9BEoQKhbW7K6IKMQqkdqwET SOx5NpS3OQiCXnPxZnDrimCpvnLOINrvbMADVHQNSbLsT+jJuXYc1IQ2nAB4Lg6U N7jwea6flFPd+ILIONxT5Qr0YAWwmn5mZwuKzIB0YjVgQZqm3qzyf/iAm9sjJx7B pRt/1oYxSwwt13c8yY45LAW/RSIFEHZMtQ9M4Q3tfnW0U2xaZ0zVRSlfDndaXCbp 4gqiFydAAXpJz7Px3dc9qBn6wiG6ps8mQ1WorRq4a8SfDn33BYDeF8E4d45qRjQ/ t+4C =CING -----END PGP SIGNATURE----- --=-=-=--