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

[Liliana Marie Prikler <liliana.prikler@gmail.com>]

Hi Katherine,

Am Mittwoch, dem 23.08.2023 um 10:25 -0600 schrieb Katherine Cox-Buday:
> 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 written 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.
The thing is, most people automate this process in some way or another.
This is a benefit of Guix' contribution model that you can't enjoy e.g.
with Github pull requests, where you basically have to sign up to a
(proprietary) service and most of the time follow whatever conditions
have been laid out by the maintainers or get your patch desk rejected.
In Guix, it's mostly humans on both ends.

> 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:
> 
>      I signed up on Savannah with the intention of applying to be a
>      committer.   Savannah closed my account one or two days later
>      due to inactivity.
I can not comment on the workings of Savannah, but as a committer
myself, I would advise against applying if you have other things in
your life that you consider more important.  While it's not the same as
being responsible for another human, being responsible for a set of
packages can be an emotional burden

>      I can't ever seem to get the GNU style commit messages correct. 
>      I use the templates provided, but those don't cover all cases, 
>      and I've even gotten feedback in a review to change a message 
>      it created.
It is the task of the committer to actually sign off meaningful commit
messages.  As long as you make an effort to keep with the general
style, little mistakes here and there are forgiven and most often
automatically corrected.

>      I don't use the email-based patch workflow day-to-day, so this
>      is another area where I spend a lot of time trying to make sure
>      I'm doing things correctly.
> 
>      My script runs `guix style` and `guix lint`, but its suggestions
> aren't always correct. I suspect I've submitted some patches
>      with nonsensical changes due to implicitly trusting these tools.
We are quite aware that those tools aren't perfect and at least some of
us recognize their "handwriting" quite easily.

>      Maybe 
> https://lists.gnu.org/archive/html/guile-devel/2023-02/msg00030.html
>      addresses this, but manually managing Guile imports is
>      laborious. As a fledgling schemer, I often forget which imports
>      I needed just for development.
Guix actively fights these import troubles by trying to give you useful
hints as to which modules to include.  Granted, this isn't too
different from your C compiler telling you that you forgot a semicolon,
but it's better than the undefined variable warnings in other contexts.

> I think I would summarize the core of these examples as:
> 
>      "At every step of the contribution process, I must manually 
>      check that multiple things are correct. With limited available
>      executive functioning, and no automation, this is very difficult
> to do correctly, and an easy place 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 are 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 more abstract issue: (should/how do) we reduce
> friction for making contributions?
> 
> Here are some things I've considered:
> 
> * Contributing to Guix is not for you
> 
>      I would be really sad if someone ever said this, but I guess
>      it's a possibility. Maybe someone like me just can't be a
>      contributor to Guix until I have the bandwidth to manage all the
>      details. I would preemptively argue that diversity of thought
>      and experiences usually leads to better things.
I think you have to separate contributing and being a committer here. 
Contributions are open to everybody (as long as they pass the first
hurdle which is a very manual check to see if they spam our mailing
lists or not), but the review process ensures that the outcome remains
high quality.  This is desirable.

Now you might say that this leads to less diversity in the team of
committers and maintainers as you need a certain level of privilege to
seriously entertain the idea of dedicating that much time and effort to
a project and I agree, but I also think this is a bigger reality of
volunteer work in general.

> * It's OK to make lots of mistakes
> 
>      The people who have reviewed my code have been generous both  
>      with their time and fixing my mistakes and then applying. Maybe
> this model is OK? I still feel guilty every time a reviewer has
>      to correct an oversight I've made. I also want to become a 
>      committer, but I don't know how that would work if I'm regularly
>      making mistakes. Obviously people would still be reviewing my
>      commits, but presumably a committer should not regularly be
>      making mistakes.
To be invited into the club of committers, you have to have existing
committers sign off on your ability to sign off commits (details in the
manual).  As you might have guessed, "I make a lot of mistakes" is not
a very convincing argument in your favour here :)

My question to you is why you feel that you want to be a committer when
you have little time to dedicate to learning our rituals and presumably
even less time to do "productive work"?  

> * We could support a managed web-based workflow
> 
>      I think this has been brought up a lot of times, and I don't
>      have a clear idea of what's been said. But I think a lot of 
>      developers these days are more familiar with this style, and we
>      could still maintain self-sovereignty if we hosted something.
Just because it's brought up a lot of times doesn't mean it's a good
idea.  There is a lot of good things that can be done for our web-based
front ends; improving the search results on issues.guix.gnu.org would
be one of them.  However, I have little hopes for a web based means to
submit contributions.  I think email should be a format that's
understood by folks who know how to operate a web browser.

> * Encourage upstream communities like "Guix 'R Us" 
> (https://sr.ht/~whereiseveryone/guixrus/)
> 
>      Maybe Guix proper continues as is and we foster various upstream
>      communities that utilize different styles and batch their 
>      contributions?
It is not the responsibility of Guix to endorse third party channels
and communities, but rather to provide the basic means to facilitate
them.  These communities have their own goals that may or may not
intersect with ours and it is up to them to decide whether contributing
any particular package or series to Guix proper is a worthwhile idea or
not.  In practice, some of them appear to be seen experimentation
grounds to see "what sticks" and contribute packages once they've
matured a bit.

Cheers