From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp12.migadu.com ([2001:41d0:403:4789::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms9.migadu.com with LMTPS id yLmjKo6T72TyXAEAauVa8A:P1 (envelope-from ) for ; Wed, 30 Aug 2023 21:07:58 +0200 Received: from aspmx1.migadu.com ([2001:41d0:403:4789::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp12.migadu.com with LMTPS id yLmjKo6T72TyXAEAauVa8A (envelope-from ) for ; Wed, 30 Aug 2023 21:07:58 +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 4C451590F4 for ; Wed, 30 Aug 2023 21:07:58 +0200 (CEST) Authentication-Results: aspmx1.migadu.com; dkim=none ("invalid DKIM record") header.d=msavoritias.me header.s=20210930 header.b=YaqFZq7m; dmarc=fail reason="SPF not aligned (relaxed)" header.from=msavoritias.me (policy=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" ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1693422478; 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: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post:dkim-signature; bh=Efd7G+xHfadwhfY785RcZIgIqERrjOHfM8+tPScA/Io=; b=qmehIngaS6Gjdaci7IDWkJtAq6drbVCSGjZf+AHfiT4EaBvpnHu//OOywrfCwUH8IYIjUz /SPit1cD9jxn53ALLIv2ZL1/wPkK4unP/0F4KUOkOp0D/DsF075NOPb6kAAvvLgxVbBm8U wlu5GusQuP+ZUS4LR60sXy1URRSsG7fttDF9L06kbuTTfdU+mNv8retHZXpcDv9Def1TZv B7DmZDBUvrSRtJlbDePnyLmYMD0U8/b5Imf8TXQG+RyyjvBrK0zD0OB/XsqBx0qNK955pR B/Atn4SD2C5ONjIJ+xVPaNz6usE5gG414mHmZH7WUyq9KyDovh207fIDB4e+tg== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=none ("invalid DKIM record") header.d=msavoritias.me header.s=20210930 header.b=YaqFZq7m; dmarc=fail reason="SPF not aligned (relaxed)" header.from=msavoritias.me (policy=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" ARC-Seal: i=1; s=key1; d=yhetil.org; t=1693422478; a=rsa-sha256; cv=none; b=KEYoq473J3+LHpIUI9rq0nYaNTuPxBEG8eazfa1icxmgNBFA91KJKfyUx7zODfEIS3oLhc aeBql+xFtSf/u5J18vZOepv5mSxAKGl897P3T5pxtkmpsGwKfE79P2wlcXb8H7HTmLjfu1 mCUamFNm4XY4VDXm6CD2sdDUVHve+pwLvnF1iSofYKEBbKJm6LI++cWtqKmD3RN0cMSijX nZYIApmYc1sZsHZs8zlrL9ciRNYqeU2wCMfqSJUba7eMZE4qRGXEbnPECD9Duprlpd4Ro9 kh/CQcG7/eFX2oQBOr4pZ8FHTyrzcH9OJNQGeFYpALFOHHcUESx65ueBBevcOA== Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qbQXS-0008Qw-H8; Wed, 30 Aug 2023 15:07:38 -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 1qbQXP-0008Qa-FH for guix-devel@gnu.org; Wed, 30 Aug 2023 15:07:36 -0400 Received: from mail.webarch.email ([81.95.52.48]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qbQXL-0008Ob-1M for guix-devel@gnu.org; Wed, 30 Aug 2023 15:07:34 -0400 Received: from [127.0.0.1] (localhost [127.0.0.1]) by localhost (Mailerdaemon) with ESMTPSA id ABE4E1A8D180; Wed, 30 Aug 2023 20:07:22 +0100 (BST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=msavoritias.me; s=20210930; t=1693422443; h=from:subject:date:message-id:to:cc:mime-version:content-type: content-transfer-encoding:in-reply-to:references; bh=Efd7G+xHfadwhfY785RcZIgIqERrjOHfM8+tPScA/Io=; b=YaqFZq7mOfgVM+micQYws+WZrinv9kiy47xF6h+xikKJsVW/YbSfG7407T/iWQtBDJi1dR Syo8oCrxJ2iobq9jWWLUCB8ya/oco0V3la66wmKNqaneyAIHLKp13iXVe+hfXHO8cdSOgC Fpv0D9FI+Jp0vCSWv/+aV4Yl3yWkNlLlAoIiSCLDVTPp/GVydfbE1pgZHmbvEzYfMTFE2l hbjrw66kuKkbMew85EIEBtCU2OoofKfSm7zJDFgy3iJ3vjuP/B71D5nHQsADIoL329BI0f ELVkuo42L+PJ9OLcHD7oxXAHxDas9J+gMFwPPLL70JYMThFSsm9PbGEhN7MqfA== References: <871qfsuvad.fsf@gmail.com> <8e74c4ac-a6f3-9127-7e13-593a2eb70432@gmail.com> <87a5ubqxm6.fsf@gmail.com> User-agent: mu4e 1.10.5; emacs 28.2 From: MSavoritias To: Katherine Cox-Buday Cc: Simon Tournier , guix-devel@gnu.org Subject: Re: How can we decrease the cognitive overhead for contributors? Date: Wed, 30 Aug 2023 22:02:41 +0300 In-reply-to: Message-ID: <87zg28l57d.fsf@fannys.me> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Last-TLS-Session-Version: TLSv1.3 Received-SPF: pass client-ip=81.95.52.48; envelope-from=email@msavoritias.me; helo=mail.webarch.email X-Spam_score_int: -16 X-Spam_score: -1.7 X-Spam_bar: - X-Spam_report: (-1.7 / 5.0 requ) BAYES_00=-1.9, DKIM_INVALID=0.1, DKIM_SIGNED=0.1, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=no 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-Flow: FLOW_IN X-Migadu-Country: US X-Migadu-Scanner: mx1.migadu.com X-Migadu-Spam-Score: -2.13 X-Spam-Score: -2.13 X-Migadu-Queue-Id: 4C451590F4 X-TUID: nPmXaCL8jpEN Yep completely agree with all of this. Personally I dont think its necessery to move to sourcehut but from the discussions I saw debbugs does seem to become a burden the more time passes on. One of the weirdest things for me in guix is how its based on scheme which is designed to be hacked in place and instead we have so many complicated steps to do it. A much more logical thing as bare minimmum is like you said: Have it as a subcommand in guix. The first thing i tried to do to contribute personally was to just do a 'guix edit' and edit the package but turns out not only i cant do it as easy as that but I also need to clone a repo and run multiple scripts inside a container(?). We should work on moving as close to a 'guix edit' and 'mumi push' contribution as possible. MSavoritias Katherine Cox-Buday writes: > Summary of my conclusions: > > 1. We should use sourcehut or continue to improve mumi > =C2=A0=C2=A0 - QA status should be visable from a patch's page=20 > =C2=A0=C2=A0 - It should be possible to interact with the issue through t= he page > > 2. We should create scripts/sub-commands to lift contribution > activities 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 > > 3. We should reify a way for Guix, the project, to measure, and track > progress, > =C2=A0=C2=A0 against long-term goals. Particularly when they're social an= d not > strictly > =C2=A0=C2=A0 technical. > > On 8/28/23 4:17 AM, Simon Tournier wrote: >> Hi Katherine, >> >> On Fri, 25 Aug 2023 at 19:02, Katherine Cox-Buday > wrote: >> >>> I think there's utility in distinguishing between familiarity and >>> eliminating toil. I think it was incorrect of me to suggest forming >>> habits in my original message. I think it's better to focus on >>> eliminating toil so that whatever workflow remains can more easily be >>> habituated. >> >> Since I am French, I am good as moaner and I would like to avoid the >> ramblings of some grumble party. :-) >> >> I agree with you that it is important to reflect ourselves about our >> practises and we need to be critical about what does not suit us. >> >> 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 > --localstatedir=3D/var --sysconfdir=3D/etc` > =C2=A0 2. Run `make` > =C2=A0 3. You need to determine whether the change can be targeted against > main or > =C2=A0=C2=A0=C2=A0=C2=A0 needs to target a feature branch, so you go read= about that. > > [I'm usually starting here] > > =C2=A0 4. Run `./pre-inst-env guix refresh --list-dependent ` > =C2=A0 5. Create a git worktree for your patch > =C2=A0 6. Run `./bootstrap`, then `./configure --localstatedir=3D/var > --sysconfdir=3D/etc` > =C2=A0 7. Run `make` > =C2=A0 8. Make your changes > =C2=A0 9. Build to ensure your changes are workable. > =C2=A0 10. Try and determine how your changes should be factored into ind= ividual > =C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 commits (sometimes it's not always so clea= r when changing two > things might > =C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 need to be done atomically). > =C2=A0 11. Try and get each commit message close to correct and commit. > =C2=A0 12. Run `guix lint` > =C2=A0 13. Run `guix style` (this is still in the manual although I have = since > =C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 learned this is not actually advisable). > =C2=A0 14. Review the changes these tools have made, and fix things. > =C2=A0 15. Run `guix build --rounds=3D2 ` to check for idempoten= cy. > =C2=A0 16. Run `make` to ensure you didn't break anything elsewhere in Gu= ix. > =C2=A0 17. Run `guix size` to ensure the closure isn't becoming bloated. > =C2=A0 18. Build all the packages that depend on this package. > =C2=A0 19. Run `guix pull --url=3D/path/to/your/checkout > --profile=3D/tmp/guix.master` to > =C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 ensure you didn't break Guix in a differen= t way. > =C2=A0 20. Run `git format-patch -1 --cover-letter [--reroll-count]` > =C2=A0 21. Run `./pre-inst-env ./etc/teams.scm cc-members ` to get > the CC flags for Git > =C2=A0 22. Remember that if you're sending multiple patches, an email fir= st > has to be > =C2=A0=C2=A0=C2=A0=C2=A0=C2=A0 sent to `guix-patches@gnu.org` to get an I= D, and then... > =C2=A0 23. Run `git send-email --to guix-patches ` > > I view steps 1-10 as pretty standard "development" steps common to most > projects, although 11 compounds the effort in 10. > > 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 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. > > For me, steps 20-23 are bothersome. There's a lot of "if" statements > that lead > to branching operations, and a lot of commands and flags to get > right. The extra > step to get a debbugs ID is annoying. > > 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 > 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. > =C2=A0 14. Wait for CI to tell you if anything is wrong. > > So now that I've enumerated the steps, compared them to contributing > to projects > I don't find difficult, and reflected on the difference for awhile, I > think, at > least for me, the highest friction comes from: > > - Steps 11-19, or (to assign it a name for easier reference) the "CI step= s". > > =C2=A0 As I understand it, we're continuing to make progress in having a = nice CI > =C2=A0 pipeline (i.e. https://qa.guix.gnu.org), so maybe I need to read > more about > =C2=A0 that. If we wanted to encourage contributors to run "CI steps" > locally before > =C2=A0 submitting, maybe this should be another `guix` sub-command? `guix > pre-check` > =C2=A0 or something? I know there is a potential contributor who had this > idea first > =C2=A0 who would want to hack on this. > > - Steps 19-23, or the "manage patch" steps. > > =C2=A0 I think an insight here is that the big button on forges is actual= ly > a program > =C2=A0 removing the mental overhead for you. It (1) notices you've pushed= a > branch > =C2=A0 when you visit the website and suggests opening a PR with a > link. (2) Submits > =C2=A0 the PR with appropriate settings (3) Recommends reviewers which you > can add > =C2=A0 after the fact. > > =C2=A0 Also, this workflow doesn't change whether you have one commit or > two in your > =C2=A0 branch, and it doesn't doesn't change when you need to submit > follow-ups (e.g. > =C2=A0 changing flags on `git format-patch`). > > =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 chang= elog > =C2=A0 messages is that it's the worst of both spoken language and progra= mming > =C2=A0 languages: there's an expectation of structure, but no grammar I c= an > parse > =C2=A0 against, and it's free-form. > > =C2=A0 I would probably have to learn more about it before making this > assertion, but > =C2=A0 it also seems like any information it provides can be fetched from > git. And > =C2=A0 when it comes to the steps to contributing, the answer is "memoriz= e these > =C2=A0 flags", but when it comes to retrieving this information, the answ= er > is "this > =C2=A0 is easier". I'm not sure about this is a fair comparison, but it m= ight be > =C2=A0 something to collectively reflect on. > > - 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 > everything 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 > not even > =C2=A0 aware that there's a QA process failing (2) If you're not using em= ail, > =C2=A0 context-switching between this page and email to respond. > >> It could be a starting point for something going to etc/ similarly as >> etc/committer.scm or etc/teams.scm.=C2=A0 Well, etc/guix-install.sh some= how >> started as a script for eliminating toil =E2=80=93 it looks similar as t= he >> situation: all the steps are described in the manual but they are too >> many effort for installing and most newcomer were dropping before >> completing. > > Yeah, after sitting with this a bit, I think this, or new Guix > sub-commands, is > probably a good path forward. The way I'm thinking about this is that > we need to > lift the individual steps into higher-order activities and have the > higher-order > activities encapsulate flags and whatnot. > > Thinking about all of this, I am reminded of this[1] picture. If we > want more > contributions to Guix, we have to do better at providing equitable > ways to work. > Focusing on this benefits everyone because it makes contributing easier f= or > everyone. > > If you're so inclined, for a bit of fun, and as a crude way of simulating > compromised executive functioning, imagine that between each of the > steps above, > a year passes. And reflect on what it would be like to gather the energy = to > start the process of starting a contribution of some kind, let alone > follow it > through to completion. > > And finally, I'm wondering how Guix, the project, tracks metrics on > these kinds > of things? If we wanted to make contributing easier, that's something > we have to > create a metric for and track over time. Is there a precedent for this > in Guix? > > [1] > https://external-content.duckduckgo.com/iu/?u=3Dhttps%3A%2F%2Fwww.lrhsd.o= rg%2Fcms%2Flib%2FNJ01000316%2FCentricity%2FDomain%2F1239%2FEquity%2520graph= ic.jpg&f=3D1&nofb=3D1&ipt=3D507d2c18cd2643bcb9ba2a67a13dc86d1926301212aaf04= bcefc3d17571f982e&ipo=3Dimages