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

[Csepp]

Katherine Cox-Buday <cox.katherine.e@gmail.com> 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 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.
>
> 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'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.
>
>     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.
>
>     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.

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:
>
>     "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 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
>
>     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.

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
>
>     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.

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/)
>
>     Maybe Guix proper continues as is and we foster various upstream
> communities
>     that utilize different styles and batch their contributions?
>
> 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.