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

[Efraim Flashner]

On Fri, Sep 08, 2023 at 11:53:43AM +0200, Giovanni Biscuolo wrote:
> Hello Katherine,
> 
> Katherine Cox-Buday <cox.katherine.e@gmail.com> writes:
> 
> [...]
> 
> > 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.
> 
> [...]
> 
> > 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.
> 
> AFAIU you are talking about the "Formatting Code" /subset/ of a "Coding
> style", because there is no linter that will tell you if you are
> following the subset called "Data Types and Pattern Matching" [1]: am I
> wrong?
> 
> Back to the git commit message formatting: please can you provide us
> with one or two examples of how a commit message should be formatted and
> what linter is available for that syntax?
> 
> [...]
> 
> > Here is my channel with things I intend to upstream, but haven't,
> > largely because of this friction.
> 
> By "this friction" you mean you miss a linter for commit messages?
> 
> Or do you mean you do not agree with the style requested by Guix (and
> GNU) for the commit messages?
> 
> You are obviously free not to contribute your patches upstream but the
> fact that you decided not to because it's "too hard" (my executive
> summary about your complaints about Change Log content rules) to write
> commit messages suitable for contribution it _not_ a Guix maintainers
> fault, not at all.
> 
> Obviously everyone is free to comment, ask for clarifications or
> proposing **patches**, but it's not fair to say "I'm not contributing
> largerly because I've a specific friction with the rules about commit
> messages" (again, my executive summary).
> 
> [...]
> 
> Ciao, Gio'

That wasn't my read of it at all. I too have many packages which I
haven't upstreamed. One of the major pushes that I did was cleaning up
mailman and pushing them to Guix. I had just finished working on it
earlier in the week and it turned out I didn't actually need it anymore,
but I figured better in Guix than out. It was either one or two 8 hour
days of reviewing my own patches, making sure they all built correctly,
and then finally committing them. I also have almost 500 go packages
which I don't intend to upstream. I'm package them and update them
occasionally when trying to package some big application like gitea or
keybase or tailscale or gotosocial, but the effort to go through and see
which packages are ACTUALLY needed and to clean up everything, it's just
too much for me.

I suppose this could be construed as "I'm not contributing these
packages because I don't like go" but that's not the whole of it. And by
rephrasing it like that takes out the nuance of other bits of why I
haven't worked on those packages and neuters the discussion about why
these are my packages instead of our packages.

As far as commit messages, I've found that the script in
etc/committer.scm to be very nice, even if there are plenty of cases
where it doesn't do the job. I do think there's room for improvement and
that may be one of the things we can do to make contributing easier.

-- 
Efraim Flashner   <efraim@flashner.co.il>   רנשלפ םירפא
GPG key = A28B F40C 3E55 1372 662D  14F7 41AA E7DC CA3D 8351
Confidentiality cannot be guaranteed on emails sent or received unencrypted

signature.asc
Description: PGP signature