From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp11.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 EE6nLKvR52Tn4AAASxT56A (envelope-from ) for ; Thu, 24 Aug 2023 23:54:51 +0200 Received: from aspmx1.migadu.com ([2001:41d0:403:4789::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp11.migadu.com with LMTPS id KNt6LKvR52Qx6gAA9RJhRA (envelope-from ) for ; Thu, 24 Aug 2023 23:54:51 +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 0F9B539267 for ; Thu, 24 Aug 2023 23:54:51 +0200 (CEST) Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=riseup.net header.s=squak header.b=XR+K6WMJ; 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=pass (policy=none) header.from=riseup.net ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1692914091; 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=kKzCBnv7YP/bs/+mJWwiqpSd0nIKJgpRfBG+99Cetb0=; b=ggzABM4ttkGY/5sIhIVTOr/xuoMMuA9WEhSAiK3OKPTFgidrLQWFG94lTAkKiLjtsGLXlj z5lwVdMOgv7yODg1g8gBwVTeQHrPsezFjkzsaErcZUQaovCAOdaeuNjTSVYWwbMnDFkOM4 DZ+rXbTI+WxFD0UF6VdWLzE5/8pv5RoaT/Nm0Yk/KSL0BqGYlx4fSd2Ly3RaJGhbv19Z43 aG9G4FLE/UYdU0vl81bjbH/WMmvBkKCTHt3uAPFvOVkCjrsC9y713N1o37OkxZ3RAIVwl5 oM5N+azddr9zP76qxmvyEd1Rhw09V5Zxn9n+ff2V0Y8FzKZEHg8FpMJToM76Bg== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1692914091; a=rsa-sha256; cv=none; b=sDlMNvg+sPtfuednyEPJPpUlTwGtGXUKQL+ad+QgQLeiPNrJf0qkjhorfKySwHmZMJ6ewX qL0iogZ9zKGteJ9WxL1E5GbucGgAfwRZ2KcqQCKTHl2psqM+8ICcKOQ+LYMRRQchw8ErsN EgH8kFkiF6Q2CK9ggogzvEYtIrqdttQVpBoyBiXXVkY9Wy+v/w4Vj9nKuBEYq3FpHFPFk5 TKK8DHj7b78BEev5RZeyIceUCKtws4wl4JoeKBsQyDFCIGKS8f27ucMt4vpcTMVSioVgdo TQWpS+2JWh5ZwTky1dWJ3dXrHeh7Oeo+2cr1mZp8YoMiN6HYZjnbkRBFR0KvGQ== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=riseup.net header.s=squak header.b=XR+K6WMJ; 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=pass (policy=none) header.from=riseup.net Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qZIHT-0005TM-Jz; Thu, 24 Aug 2023 17:54:19 -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 1qZIHS-0005T5-CZ for guix-devel@gnu.org; Thu, 24 Aug 2023 17:54:18 -0400 Received: from mx0.riseup.net ([198.252.153.6]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qZIHO-0002Jp-3Q for guix-devel@gnu.org; Thu, 24 Aug 2023 17:54:17 -0400 Received: from fews02-sea.riseup.net (fews02-sea-pn.riseup.net [10.0.1.112]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx0.riseup.net (Postfix) with ESMTPS id 4RWxgS1gR6z9t7J; Thu, 24 Aug 2023 21:54:12 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=riseup.net; s=squak; t=1692914052; bh=013A1gMuQSUv1DNVqdVo68XKRqbErSWBUVcZ6OLexHI=; h=References:From:To:Cc:Subject:Date:In-reply-to:From; b=XR+K6WMJya1wGqq+GqW6PqZw/YFFkslQYx5YnBuTmyE85+qrg8TylCiB3Lofu5bsy 3MpmBI51KaiTM3Ntzu77siGhRqFbpuYW0jI3t4TF89wnd2yoNHv0VqGjZCX46SXzhj sWkI0G10yYkdOGbcNfsLIUKXzHV5mK5WmVRUGjFs= X-Riseup-User-ID: 89B0EDBC851DCD3DA6CB97B5649099B5390322D6B761B9E90778B686E1638FBE Received: from [127.0.0.1] (localhost [127.0.0.1]) by fews02-sea.riseup.net (Postfix) with ESMTPSA id 4RWxgR3qsRzFpcn; Thu, 24 Aug 2023 21:54:11 +0000 (UTC) References: From: Csepp To: Katherine Cox-Buday Cc: guix-devel@gnu.org Subject: Re: How can we decrease the cognitive overhead for contributors? Date: Thu, 24 Aug 2023 02:18:03 +0200 In-reply-to: Message-ID: <871qfsayyx.fsf@riseup.net> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Received-SPF: pass client-ip=198.252.153.6; envelope-from=raingloom@riseup.net; helo=mx0.riseup.net X-Spam_score_int: -17 X-Spam_score: -1.8 X-Spam_bar: - X-Spam_report: (-1.8 / 5.0 requ) BAYES_00=-1.9, DATE_IN_PAST_12_24=1.049, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, 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-Flow: FLOW_IN X-Migadu-Country: US X-Migadu-Spam-Score: -5.77 X-Spam-Score: -5.77 X-Migadu-Queue-Id: 0F9B539267 X-Migadu-Scanner: mx1.migadu.com X-TUID: Ath/ahpK+FTY Katherine Cox-Buday writes: > Summary: for people who don't contribute to Guix a lot, each > contribution has > very high cognitive overhead. Can we work to reduce that? > > Hey all, > > Contributing to Guix is currently pretty difficult for me. I'm a Mom with= a > full-time job, and anything outside of my job that requires a lot of > executive > functioning (e.g. lots of manual, detailed, steps) is very difficult > for me to > get correct. That last part is what I wanted to discuss, because > that's the part > that prevents me from contributing more than I do, and I think there are > probably others whom are impacted by this. > > When I have some time to contribute, I usually stall out at the > "submit this for > review" because of the amount of cognitive overhead required. I've writte= n a > script for myself that tries to perform all the steps including > running the git > command to submit the patch, and this has helped me, but that this is > necessary > for me to do might be something that, if addressed, could help others. > > Here are some examples of things that cause issues for me. This is not > a list of > grievances; it's my way of attempting to demonstrate the "shape" of > the issue: > > =C2=A0=C2=A0=C2=A0 I signed up on Savannah with the intention of applying= to be a > committer. > =C2=A0=C2=A0=C2=A0 Savannah closed my account one or two days later due t= o inactivity. > > =C2=A0=C2=A0=C2=A0 I can't ever seem to get the GNU style commit messages= correct. I > use the > =C2=A0=C2=A0=C2=A0 templates provided, but those don't cover all cases, a= nd I've even > gotten > =C2=A0=C2=A0=C2=A0 feedback in a review to change a message it created. > > =C2=A0=C2=A0=C2=A0 I don't use the email-based patch workflow day-to-day,= so this is > another > =C2=A0=C2=A0=C2=A0 area where I spend a lot of time trying to make sure I= 'm doing things > =C2=A0=C2=A0=C2=A0 correctly. > > =C2=A0=C2=A0=C2=A0 My script runs `guix style` and `guix lint`, but its s= uggestions aren't > =C2=A0=C2=A0=C2=A0 always correct. I suspect I've submitted some patches = with nonsensical > =C2=A0=C2=A0=C2=A0 changes due to implicitly trusting these tools. > > =C2=A0=C2=A0=C2=A0 Maybe > https://lists.gnu.org/archive/html/guile-devel/2023-02/msg00030.html > =C2=A0=C2=A0=C2=A0 addresses this, but manually managing Guile imports is= laborious. As a > =C2=A0=C2=A0=C2=A0 fledgling schemer, I often forget which imports I need= ed just for > =C2=A0=C2=A0=C2=A0 development. This definitely falls into the IDE tooling issue that I complained about a bunch of times. There seems to be a reality distortion field around Lisp that makes some users believe that s-expressions automatically lead to a good IDE experience. And yet, Java IDEs have had automatic import management for at least 15 years (around the time I first used Eclipse), but Guile still doesn't have anything of the sort. It looks like the only way to move forward is for people to share these helper scripts they've been using and forging them into a consistent developer environment, maybe based on Guile Studio. Hopefully I can make some contributions towards such a project. > I think I would summarize the core of these examples as: > > =C2=A0=C2=A0=C2=A0 "At every step of the contribution process, I must man= ually check that > =C2=A0=C2=A0=C2=A0 multiple things are correct. With limited available ex= ecutive > functioning, > =C2=A0=C2=A0=C2=A0 and no automation, this is very difficult to do correc= tly, and an > easy place > =C2=A0=C2=A0=C2=A0 for contributors to stop." > > I think that if I were working on Guix more frequently, I would build > habits I > didn't have to think about, and these wouldn't be the large issues they a= re > for me. But because of the nature of a project like Guix, we want > contributions > from people of all kinds of backgrounds, not just people who have the > privilege > to work on Guix a lot. > > I have given a list of issues to a group of people who are presumably > analytical, and I think the natural inclination is to go > point-by-point and make > arguments for/against. Instead of that[*], I invite you to address the mo= re > abstract issue: (should/how do) we reduce friction for making contributio= ns? > > Here are some things I've considered: > > * Contributing to Guix is not for you > > =C2=A0=C2=A0=C2=A0 I would be really sad if someone ever said this, but I= guess it's a > =C2=A0=C2=A0=C2=A0 possibility. Maybe someone like me just can't be a con= tributor to > Guix until > =C2=A0=C2=A0=C2=A0 I have the bandwidth to manage all the details. I would > preemptively argue > =C2=A0=C2=A0=C2=A0 that diversity of thought and experiences usually lead= s to better > things. I really hope we can lower the barrier to entry without sacrificing code quality precisely because of this. Lots of important use cases that Guix could serve are ignored because the people who need them are not represented in our community and/or they can't contribute and no one is able/willing to write code for them. > * It's OK to make lots of mistakes > > =C2=A0=C2=A0=C2=A0 The people who have reviewed my code have been generou= s both with > their time > =C2=A0=C2=A0=C2=A0 and fixing my mistakes and then applying. Maybe this m= odel is OK? > I still > =C2=A0=C2=A0=C2=A0 feel guilty every time a reviewer has to correct an ov= ersight I've > made. I > =C2=A0=C2=A0=C2=A0 also want to become a committer, but I don't know how = that would > work if > =C2=A0=C2=A0=C2=A0 I'm regularly making mistakes. Obviously people would = still be > reviewing my > =C2=A0=C2=A0=C2=A0 commits, but presumably a committer should not regular= ly be making > =C2=A0=C2=A0=C2=A0 mistakes. In a sense I agree with this, but if mistakes are this easy to make, then I think something is wrong with the project, not with the contributor. Instead of making people learn tightrope walking, maybe we should be building actual bridges. Guix actually fares pretty well in this regard compared to some other projects I tried contributing to (*stares at Plan 9*), but there is still a lot of knowledge that experienced developers take for granted and don't actually document. Writing new packages is mostly documented well, but as soon as something breaks, you are thrown into the deep end, having to dissect logs, bisect commit ranges, learn strace, gdb (which still doesn't work well on Guix), learn how to compile packages with debug info (and actually waste some more CPU time and IO on rebuilding a package you already have), learn how to adapt docs from other distros, etc, etc, etc. I've been trying to document these at least for myself, but haven't yet had time to put them together into something others could read. By the way, that's another issue. Using a TeX based document format for the docs is, uuuh, maybe not the best idea. Info is a pretty okayish documentation reader, but it's a relatively big barrier to entry compared to what you need to know to make a small edit to the Arch wiki. This way mostly just experienced contributors write docs, not the users who just want to document how they made some weird use case possible. > * We could support a managed web-based workflow > > =C2=A0=C2=A0=C2=A0 I think this has been brought up a lot of times, and I= don't have > a clear > =C2=A0=C2=A0=C2=A0 idea of what's been said. But I think a lot of develop= ers these > days are > =C2=A0=C2=A0=C2=A0 more familiar with this style, and we could still main= tain > self-sovereignty > =C2=A0=C2=A0=C2=A0 if we hosted something. I'm very much in favor of using Sourcehut, since there are people whose actual main job is to improve Sourcehut. There was also a project (although it currently seems to be stalled) at Sourcehut that aimed to sync pull requests on forges like GitLab with patches on Sourcehut, if that was completed we could even have a Gitea instance for people who aren't comfortable with the email workflow. > * Encourage upstream communities like "Guix 'R Us" > (https://sr.ht/~whereiseveryone/guixrus/) > > =C2=A0=C2=A0=C2=A0 Maybe Guix proper continues as is and we foster variou= s upstream > communities > =C2=A0=C2=A0=C2=A0 that utilize different styles and batch their contribu= tions? > > What do you all think? Does this affect anyone else? > > [*] But if you have workflow suggestions, I'm all ears! Personally I think these should at least be linked, even The Forbidden Channel We Shall Not Name (but at least 50% of us are likely using). It's better to direct users to a community that can help them when this one can't.