From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp10.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 cJDnJkpq72SuYgEAG6o9tA:P1 (envelope-from ) for ; Wed, 30 Aug 2023 18:11:54 +0200 Received: from aspmx1.migadu.com ([2001:41d0:403:478a::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp10.migadu.com with LMTPS id cJDnJkpq72SuYgEAG6o9tA (envelope-from ) for ; Wed, 30 Aug 2023 18:11:54 +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 580CC374F0 for ; Wed, 30 Aug 2023 18:11:54 +0200 (CEST) Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20221208 header.b=MvNj8xuK; dmarc=pass (policy=none) header.from=gmail.com; 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=1693411914; 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: 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=jIGHCHXRyFp05f7MiiHNFW21MARxzAzhcEnNGSpcSz0=; b=UX96oXgHptFYwjXZhTeBv/+E84Fz4Ssl8VGlIWw7MCGWUgzCmp4omfdrHNfpHDBNNfvXrP VfyJS47YRe0/zIyGqzs/TMYMzmvWb4R6yAxbYD2sdD4TaQv0JNHc3YmQFOEcR4bm5bCaJY zQXrhtSvudIXQ3tpPuPSqOMpmucCKYUsXYAPXuD8/aNK6/mFK4XqNL+Rt7cVhwLvtjjeg4 0UdxI3NM1HoTxuE7MmYUq/iauEvCJI/Nnp+FiR/H0IbHVoV1diM2xMB4iaePi1sey/PRmb ANb6/rYLt3XzpcSYnJD8ZXFtuPzPA3nU3uA3xa88j2GOfgTxRd00DwdwAOj1Bg== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20221208 header.b=MvNj8xuK; dmarc=pass (policy=none) header.from=gmail.com; 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=1693411914; a=rsa-sha256; cv=none; b=X7Wf5bi6zxU24UG1RUJzU+1Xw/A4w1u3X2L6jHEK0kbb8picTaT+S7RWDBXWvh0mMIfPO9 WXPhBcRNRqpgo68zu6mzpA61U/fNHqIjuYrUOXqyC5bmDsZy1wwJ4hj2VW/DYNJwgqJ7x3 /t/K4ectJABfXu9HUB9yYLOrMX8qO+4m1w0wf/fgstsbBnKRsKm2JOjINiTlyiku6I7D6z RroHUvql99MkKvYjxx2r/5gUFiYwPwW/9MP3WAe5oiKO6a4Uv2ZHIc/B96G2wdAJsMPOdL pwSG5SSHc6FXKz8nrHWHPSp5DSpgpw5VgFzdTiwyda/WrUDgBJjq2b/9yRMQ3Q== Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qbNmg-000581-SN; Wed, 30 Aug 2023 12:11:10 -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 1qbNme-00057e-PY for guix-devel@gnu.org; Wed, 30 Aug 2023 12:11:08 -0400 Received: from mail-io1-xd34.google.com ([2607:f8b0:4864:20::d34]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1qbNmb-0002pR-Qe for guix-devel@gnu.org; Wed, 30 Aug 2023 12:11:08 -0400 Received: by mail-io1-xd34.google.com with SMTP id ca18e2360f4ac-792707f78b5so193849839f.1 for ; Wed, 30 Aug 2023 09:11:05 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20221208; t=1693411864; x=1694016664; darn=gnu.org; h=content-transfer-encoding:in-reply-to:from:references:to :content-language:subject:user-agent:mime-version:date:message-id :from:to:cc:subject:date:message-id:reply-to; bh=jIGHCHXRyFp05f7MiiHNFW21MARxzAzhcEnNGSpcSz0=; b=MvNj8xuKc5PWDLTcpuQCeoxbkbxjJBNGixjoivrOnFQbbRNqAJ2i1m/nTdplZ1q2vd ihD0M9KkRsp4SGS+OzjsdFR7CLiz5Os4A5+ZKgyiRMWENTAtXDLg+rQGzuz3F1NJ1uhz nu6v/DhCXmnLzGvcnhbYVM+qFJCFXqbhf6CyZ47ZpCOgGPIpFDxVyOijttK2/ywZSA4Y 4HaD1KTrRbAYRQ88is9euay4th03QwQHxrrHguHNiWZqDsJbu625RTY33gBG/Rehvf/l Mb1/lw32Me4p+kG+vv9JtDHmsBU4KFsd/tv6tDl1iech0mtFoJ8fUpU/PE14GyrDHY+O 7zlQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1693411864; x=1694016664; h=content-transfer-encoding:in-reply-to:from:references:to :content-language:subject:user-agent:mime-version:date:message-id :x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=jIGHCHXRyFp05f7MiiHNFW21MARxzAzhcEnNGSpcSz0=; b=KI+b5s3GJb2dnJZ+PKhIwyj1t++ByBeXoEN2T6kGm24htZomk2PUQNwiBFKm6QLEER dSsDsqIFF4S6e3vkVNVjNP4H2gqsCrOAN45PvESfbXC79KwLCc5zJ/G7z331A289PaUv H28dOuQMYB1NfZB3PXoXNMa2XtshW2EbaXgQPv4VcLcmQC26VHO9i+muewTUr2KSV5+p +7CnexWZ2esX3cB6qfpohWrm8cLoJGlhC732VTAomZ4++LzEvbss1L5KNbHZEYxP9iKs yMXHYooihrGodPOWpBO+tYB+4IcZ4GZitXuzUHE4HavMuibi+o92LB7iTSoK5zHbZVsV aHtw== X-Gm-Message-State: AOJu0YwRLr/p0Ls8yFWTemeH3gUBlFoQkZJ+xrkAAvrCNM3aJGig+zp0 HwynkTUwDe3Ol7oYyDFm4Zs= X-Google-Smtp-Source: AGHT+IG7KIAtOpOTfwljfrFGhHPVvTIF5t12BC24cMoPPutPzq/SYhiI6BRQyON84YRYQYDKdpB6Ag== X-Received: by 2002:a5e:8a48:0:b0:790:c259:4ee5 with SMTP id o8-20020a5e8a48000000b00790c2594ee5mr3172195iom.8.1693411864126; Wed, 30 Aug 2023 09:11:04 -0700 (PDT) Received: from [10.0.2.153] (c-174-51-218-141.hsd1.co.comcast.net. [174.51.218.141]) by smtp.gmail.com with ESMTPSA id z11-20020a02ceab000000b00418a5e0e93esm3906511jaq.162.2023.08.30.09.11.02 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Wed, 30 Aug 2023 09:11:03 -0700 (PDT) Message-ID: Date: Wed, 30 Aug 2023 10:11:02 -0600 MIME-Version: 1.0 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.13.0 Subject: Re: How can we decrease the cognitive overhead for contributors? Content-Language: en-US To: Simon Tournier , guix-devel References: <871qfsuvad.fsf@gmail.com> <8e74c4ac-a6f3-9127-7e13-593a2eb70432@gmail.com> <87a5ubqxm6.fsf@gmail.com> From: Katherine Cox-Buday In-Reply-To: <87a5ubqxm6.fsf@gmail.com> Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 8bit Received-SPF: pass client-ip=2607:f8b0:4864:20::d34; envelope-from=cox.katherine.e@gmail.com; helo=mail-io1-xd34.google.com X-Spam_score_int: -32 X-Spam_score: -3.3 X-Spam_bar: --- X-Spam_report: (-3.3 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001, NICE_REPLY_A=-1.242, RCVD_IN_DNSWL_NONE=-0.0001, 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-Spam-Score: -5.59 X-Migadu-Queue-Id: 580CC374F0 X-Migadu-Scanner: mx0.migadu.com X-Migadu-Spam-Score: -5.59 X-TUID: LWYpwOwrVBNK Summary of my conclusions: 1. We should use sourcehut or continue to improve mumi    - QA status should be visable from a patch's page    - It should be possible to interact with the issue through the page 2. We should create scripts/sub-commands to lift contribution activities into    higher-order concepts:    - Prepare a new submission    - Run pre-checks on a submission    - Submit a patch    - Status of patch 3. We should reify a way for Guix, the project, to measure, and track progress,    against long-term goals. Particularly when they're social and not strictly    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:   1. Check out main, and run `./bootstrap`, then `./configure --localstatedir=/var --sysconfdir=/etc`   2. Run `make`   3. You need to determine whether the change can be targeted against main or      needs to target a feature branch, so you go read about that. [I'm usually starting here]   4. Run `./pre-inst-env guix refresh --list-dependent `   5. Create a git worktree for your patch   6. Run `./bootstrap`, then `./configure --localstatedir=/var --sysconfdir=/etc`   7. Run `make`   8. Make your changes   9. Build to ensure your changes are workable.   10. Try and determine how your changes should be factored into individual       commits (sometimes it's not always so clear when changing two things might       need to be done atomically).   11. Try and get each commit message close to correct and commit.   12. Run `guix lint`   13. Run `guix style` (this is still in the manual although I have since       learned this is not actually advisable).   14. Review the changes these tools have made, and fix things.   15. Run `guix build --rounds=2 ` to check for idempotency.   16. Run `make` to ensure you didn't break anything elsewhere in Guix.   17. Run `guix size` to ensure the closure isn't becoming bloated.   18. Build all the packages that depend on this package.   19. Run `guix pull --url=/path/to/your/checkout --profile=/tmp/guix.master` to       ensure you didn't break Guix in a different way.   20. Run `git format-patch -1 --cover-letter [--reroll-count]`   21. Run `./pre-inst-env ./etc/teams.scm cc-members ` to get the CC flags for Git   22. Remember that if you're sending multiple patches, an email first has to be       sent to `guix-patches@gnu.org` to get an ID, and then...   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 runs (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:   1-10 as usual   11. Write a more commonly accepted commit message with no special formatting.   12. Run `git push` (subsequent changes are still just `git push`).   13. Go to forge website, click button to open a pull-request.   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 steps".   As I understand it, we're continuing to make progress in having a nice CI   pipeline (i.e. https://qa.guix.gnu.org), so maybe I need to read more about   that. If we wanted to encourage contributors to run "CI steps" locally before   submitting, maybe this should be another `guix` sub-command? `guix pre-check`   or something? I know there is a potential contributor who had this idea first   who would want to hack on this. - Steps 19-23, or the "manage patch" steps.   I think an insight here is that the big button on forges is actually a program   removing the mental overhead for you. It (1) notices you've pushed a branch   when you visit the website and suggests opening a PR with a link. (2) Submits   the PR with appropriate settings (3) Recommends reviewers which you can add   after the fact.   Also, this workflow doesn't change whether you have one commit or two in your   branch, and it doesn't doesn't change when you need to submit follow-ups (e.g.   changing flags on `git format-patch`).   I also don't usually have to worry nearly as much about crafting a commit   message. So long as the title is under a character limit, and the body is   helpful, it's OK. I think what bothers me most about the GNU changelog   messages is that it's the worst of both spoken language and programming   languages: there's an expectation of structure, but no grammar I can parse   against, and it's free-form.   I would probably have to learn more about it before making this assertion, but   it also seems like any information it provides can be fetched from git. And   when it comes to the steps to contributing, the answer is "memorize these   flags", but when it comes to retrieving this information, the answer is "this   is easier". I'm not sure about this is a fair comparison, but it might be   something to collectively reflect on. - Having multiple places to manage aspects of my patch   In a web-forge, I generally have a URL I can go to and see everything about my   patch. I think we have that with https://issues.guix.gnu.org with two   exceptions: (1) QA is a click away, or if you're using email, you're not even   aware that there's a QA process failing (2) If you're not using email,   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.  Well, etc/guix-install.sh somehow > started as a script for eliminating toil – it looks similar as the > 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 for 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=https%3A%2F%2Fwww.lrhsd.org%2Fcms%2Flib%2FNJ01000316%2FCentricity%2FDomain%2F1239%2FEquity%2520graphic.jpg&f=1&nofb=1&ipt=507d2c18cd2643bcb9ba2a67a13dc86d1926301212aaf04bcefc3d17571f982e&ipo=images