Re: How can we decrease the cognitive overhead for contributors?

[Katherine Cox-Buday]

On 9/5/23 4:57 PM, Simon Tournier wrote:
> Hi,
>
> On Tue, 05 Sep 2023 at 11:01, Katherine Cox-Buday <cox.katherine.e@gmail.com> 
> 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.