From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp10.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 6J1oG1Ll92SqGgEAG6o9tA:P1 (envelope-from ) for ; Wed, 06 Sep 2023 04:34: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 mp10.migadu.com with LMTPS id 6J1oG1Ll92SqGgEAG6o9tA (envelope-from ) for ; Wed, 06 Sep 2023 04:34: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 B27F15A7E4 for ; Wed, 6 Sep 2023 04:34:57 +0200 (CEST) Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20221208 header.b=NsQIBxiZ; 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=gmail.com ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1693967698; 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=6QH/626AWDUiR3+ik0GvT/F+7shEubAknX+Y5D+p5r0=; b=p8eDbTqU3jxZzEDPAvuhyu8BM8fUcMdm6XAHDqCX7vM/nSll4/unkIsLo/SU1rvpe7WOpf 8g1J07pSBOaAB7FU6PacYEi9r3FXXM6asr2Pk06KjkxjaR+k5h7v5yMTzvHocQ1/sPRxer JDNuSjt5r34RFr6NQ/69ZNXF15JJicpoYhcrjDbcYCxNA6qKkNWdNwUqIgKr9OlD9W2M3a ugZPwWpJWQB7Hb3/83+1fM8sMy9uSNZPhlaRagEg3qReBcPbua2RCv/0UxbM603Nmu+/tb 4Eo8PqEnBeM6lgpsFa0lZDEPEhK9zO84XgJGQXvd6bYcYYt78fY60pj6mPRGIQ== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20221208 header.b=NsQIBxiZ; 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=gmail.com ARC-Seal: i=1; s=key1; d=yhetil.org; t=1693967698; a=rsa-sha256; cv=none; b=RmB5aq4+AwQ+yJXMB5it1N+W62bN9NeMFTLIQX/yiYo8DnwaRXEqO9dQVkZVhoO8B2Szwx EqpF8WBIIthRiw4NRU3hQUoRI/5e+adx0aEruh8PjFb0XqkyENpy33UOgDaTOyfLtxAFWq lN5ZqpF/Pc24pchWSG6u9Cex/qBAK5JTrZzzd58OoAFTdVanWbtcfgcC1MbdKxNusFn3RW hoWS2LsxVF64Ws3hUPsu38DignHZKkA4Jy5J0BVyH9WgWj3Ilx69AOPiZhm/p5HwT3zBSb vqTR8P+3PLZAU4fGwRk+s/oiPGzVEihakhMqIPVb5+pJNLDLVbogS3ulQY4H4w== Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qdiN1-0006cw-Uo; Tue, 05 Sep 2023 22:34: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 1qdiMy-0006cg-5I for guix-devel@gnu.org; Tue, 05 Sep 2023 22:34:16 -0400 Received: from mail-io1-xd2e.google.com ([2607:f8b0:4864:20::d2e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1qdiMv-0008B2-44 for guix-devel@gnu.org; Tue, 05 Sep 2023 22:34:15 -0400 Received: by mail-io1-xd2e.google.com with SMTP id ca18e2360f4ac-7926b7f8636so13871239f.1 for ; Tue, 05 Sep 2023 19:34:12 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20221208; t=1693967652; x=1694572452; darn=gnu.org; h=content-transfer-encoding:in-reply-to:from:references:cc:to :content-language:subject:user-agent:mime-version:date:message-id :from:to:cc:subject:date:message-id:reply-to; bh=6QH/626AWDUiR3+ik0GvT/F+7shEubAknX+Y5D+p5r0=; b=NsQIBxiZE/QJlSscAIEYzHWUhy6jPPiI/4XU/qfc5lpT4EjL7ik21DGnBQdEXrtdDS qJEWUZJzBkV/E3FijSyUmm+ATMqXvF6vkapy2r6hwBDrzYHwmZZalmlSzhEtaqDyqH5h ZhwkbVP0Od5ljrF919hITE1u8bu8i/Njhsn8dphvcMuMPFJ1nwIEbfsw6WJg1DyfAwZS m4nDF93RriGb54/6z7W3MZ0Je/eXP8rZ1PJ+ob3da+s7eCGhDhUg0jx38EchqX8ptvZF YqaWT9ykKJE/0xmScI9xgdNMhCUMHvw1fJpy5AJ29mJPQXSXRuvrvZNTup+ss2NnrSjF F5Bg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1693967652; x=1694572452; h=content-transfer-encoding:in-reply-to:from:references:cc: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=6QH/626AWDUiR3+ik0GvT/F+7shEubAknX+Y5D+p5r0=; b=aZPuIZioyjdr7gRw/TucJNBF38DKR2CpsI/XwYRLILknI7Imx8gshSnUQoRwjQHX0L T696lNCjUel9vF+pe5P6EHNAnqvTGRshciQnzpcXVyAee27ipcfuM7hxuems1SZ8PYM7 zwEkBPMBO3fABwS9vDyG1YCEiG8o14OieGasZup2aQ/ehg+p+7V4Fattjxg1qehOeuSk aaCBkoc4pBDqu0+4Wzc6j/5J9gPhS15adlEVdTX4WW70FzGYGCy3xVoMZ1j3kmtx0CvS ydwH7x1sy79GDFG4uSy/OpD0MlxBkdoik/PxodVq3RDnPuOWwyLtle0IX6jCc2cfyw/K iJ2Q== X-Gm-Message-State: AOJu0YxHvG7EfSy0A6DZXU12c1z0w2vl5/bmsbW1x9YJUSs3Fjbisr3g Ehdb1YiDViU8IR0N6wWEzO8= X-Google-Smtp-Source: AGHT+IFa86xd3Yw1Xct6tUUmVaOAGQVLm5QroJLwS4ZiFTK3wRY0kKUY1VPmp4pql8lf2g2DOyvonA== X-Received: by 2002:a05:6602:498f:b0:792:96c0:f4ad with SMTP id eg15-20020a056602498f00b0079296c0f4admr15610042iob.3.1693967651612; Tue, 05 Sep 2023 19:34:11 -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 f23-20020a056602039700b007836252a084sm4658667iov.48.2023.09.05.19.34.09 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Tue, 05 Sep 2023 19:34:10 -0700 (PDT) Message-ID: Date: Tue, 5 Sep 2023 20:34:08 -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 , Maxim Cournoyer , Saku Laesvuori Cc: Attila Lendvai , Liliana Marie Prikler , Andreas Enge , "Felix Lechner via Development of GNU Guix and the GNU Systemtdistribution." References: <20230827135726.y33t55w4cvq6zsvb@X-kone> <874jkift8v.fsf@gmail.com> <867cp4sj7k.fsf@gmail.com> <38242808-2f06-4674-3842-aea1a5378d05@gmail.com> <86v8cop6sy.fsf@gmail.com> From: Katherine Cox-Buday In-Reply-To: <86v8cop6sy.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::d2e; envelope-from=cox.katherine.e@gmail.com; helo=mail-io1-xd2e.google.com X-Spam_score_int: -35 X-Spam_score: -3.6 X-Spam_bar: --- X-Spam_report: (-3.6 / 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.473, 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-Flow: FLOW_IN X-Migadu-Country: US X-Migadu-Queue-Id: B27F15A7E4 X-Migadu-Scanner: mx1.migadu.com X-Migadu-Spam-Score: -4.09 X-Spam-Score: -4.09 X-TUID: d3FJHAZ/u6vN On 9/5/23 4:57 PM, Simon Tournier wrote: > Hi, > > On Tue, 05 Sep 2023 at 11:01, Katherine Cox-Buday wrote: > >>> Well, somehow, I consider the commit message format similarly as coding >>> style. We can discuss which one is better than the other when at the >>> end it only reflects some artificial preferences and for the sake of any >>> project one needs to be arbitrarily picked. Why not ChangeLog? >> The distinction I draw is that I can usually run a linter against a >> coding style. >> >> I don't care very much what the standard for commit messages is other >> than if it has an expectation of structure, I be able to run a tool to >> tell me if it's wrong. >> >> In other words, the overhead isn't "I don't like this standard", it's "I >> can't find a way to reliably adhere to the standard". > Well, I am not sure to fully understand what you have in mind with the > term “standard“. I'm sorry if I've not explained this well, Simon. Thank you for trying to understand. By "standard" I mean the GNU Changelog format (https://www.gnu.org/prep/standards/standards.html#Change-Logs). As in: it's expected that commit messages use this format. > To me, coding style or similarly commit message format > are about standard or norm, meaning they respect a set of rules. > > The question is then: is it possible to explicitly write down all the > rules? Are all the rules all well-defined or are some ambiguous? etc. > > For some norm or standard, it is possible to have a checker because all > the rules are explicitly well-defined. For many norms/standards, we do > not have any checker. This is my point. There is an expectation, but no way to check against that expectation, and the expectation is complicated enough that it's easy to get wrong. The Changelog format is like a little language with conditionals about how "simple" the change is, and line length, and blank lines. In my response I was trying to point out a flaw in your comparison: that with style guidelines, which are also complicated, there is usually a formatter that will do it for me, or a linter that will tell me that something is not meeting the standard. This is because languages have grammars, and linters have higher-order system grammars. > Now, I have read the thread and I hear the comments about the commit > message format as ChangeLog. To be honest, I am somehow surprised. If > after being enough annoyed by something that then one clones the Guix > repository, finds how to improve and last drops all because writing the > commit message is too “complex” or because one does not know if the > commit message correctly adhere to the standard… Sorry, I do not buy. I don't think anyone has said this. To be explicit: I am not saying this. What my original message said, and what others have said, is that in aggregate, the steps to contribute produce enough friction so as to keep contributions from being proposed and merged. The commit messages are part of that aggregate. Here are others saying this in this thread:     - https://lists.gnu.org/archive/html/guix-devel/2023-09/msg00040.html     - https://lists.gnu.org/archive/html/guix-devel/2023-09/msg00051.html Here is my channel with things I intend to upstream, but haven't, largely because of this friction. It includes services and packages. https://github.com/kat-co/guix-channels/tree/upstream-staging/upstream For whatever else has been brought up in this thread, I started with this:     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     more abstract issue: (should/how do) we reduce friction for making     contributions? > And I do not buy either an issue when resuming after an interruption > because writing commit message can be done from the diff. More than > often, I tweak stuff, then commit with the oneline subject ’DRAFT foo’, > continue to tweak, commit ’DRAFT bar’. Days or weeks (or months) later, > I resume my work and run “git rebase” for polishing the commit ’DRAFT > foo’ and preparing it for submission. > > Again I hear all the comments and I am trying hard to understand. From > my point of view and from where I stand, my understanding is that the > core point of commit message format is about 1. discipline – the quality > of being able to behave and work in a controlled way which involves > obeying particular rules or standards – and 2. confidence – the willing > to send the perfect message on the first try. And there is no tool for > fixing these both issues. In the US, the phrase "I don't buy it" is usually the response to someone trying to trick you into something. This is a little hurtful because it's either saying: "You have an ulterior motive and are trying to trick me into doing something." or "I don't have the same experience as you, so you must be lying." The only thing I know to do is to respond with my experiences, and try to make plain statements about them. So I'll try and do that again here: For me at least, the overhead isn't remembering what the commit message should contain, it's remembering what the format should be. It's another step in a very long list of steps in which I need to open the GNU Changelog page side-by-side and try and meet its requirements. A common argument I'm seeing is: "The committers will fix it for you." Well, at some point I want to be a committer, so what then? I'd be happy to get second reviews from other committers to make sure the commit messages are correct, but it seems like addressing the fact that capable people struggle to get this correct is more sensible. > Yeah, commit messages are boring to write. At no point have I made this argument. I will use whatever the standard is. I'm trying to frame the conversation around how to make it easier to follow the standard, not how to get out of following the standard. > Well, I share various points that had been raised in this thread about > smoothing the contribution requirements. However, I am still puzzled by > the comments about the commit message format. Again, my inability to > understand the issue does not mean I am not hearing. Communication is so hard. My only advice is to remain aware that everyone in the world is different, and that even when we don't understand something, or don't experience it ourselves, that doesn't make it less real, especially if there's a plurality of people agreeing with one another. And to always choose kindness. Here is a great talk by Rich Hickey called "Simple Made Easy". Although I recommend watching the entire thing, I'd like to draw your attention to a few points: - Easy is relative: https://youtu.be/SxdOUGdseq4?t=497 - Differentiating the types of complexity (importantly defining incidental complexity): https://youtu.be/SxdOUGdseq4?t=1173 The crucial point of this talk for me is when Rich draws an analogy to juggling (https://youtu.be/SxdOUGdseq4?t=1353). He poses the question: you can juggle a finite number of balls; how many of those do you want to be incidental complexity balls vs. problem complexity balls. In the Guix world, how many of our balls do we want to be the meta of contributing vs. actual code checked into Guix? > All the rules are not explicitly written, IIRC, so the most reliable way > to adhere about the standard is probably to internalize these questions: > > What changes affected a particular source file? > Was a particular source file renamed or moved, and if so, as part of what change? > What changes affected a given function or macro or definition of a data structure? > Was a function (or a macro or the definition of a data structure) renamed or moved from another file, and if so, as part of which change? > What changes deleted a function (or macro or data structure)? > What was the rationale for a given change, and what were its main ideas? > Is there any additional information regarding the change, and if so, where can it be found? > > https://www.gnu.org/prep/standards/html_node/Change-Logs.html#Change-Logs > > All in all, my only proposal would to have a Git pre-commit hook or some > template pasting these questions and recalling the generic ChangeLog > format, when writing the commit message. Maybe it would help… A kind of wizard? I'm not sure if that addresses the overhead or not. Maybe that combined with a templating system that everyone can use? I don't have a lot of useful suggestions here other than to repeat something "(" said: I do think that there's a problem if the commit format is so complex that it's not trivial for anyone new to the project to write them out manually. I think it's complex because it's trying to replicate the kinds of things a SCM tool can now track, but in free-form text blocks. I'm sorry I don't have suggestions for this specific thing, other than to drop it. Above all, thanks for the dialogue.