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

[Ekaitz Zarraga]

Hi,

On Wednesday, September 13th, 2023 at 3:42 PM, Maxim Cournoyer 
<maxim.cournoyer@gmail.com> wrote:

> 
> There's no lock-in. You can use any tool you want. Most people hacking
> on Guix do so with Emacs and Geiser because these are currently the best
> tools (that I know of) to do the job; these are the tools many of us
> know and can easily recommend. If Visual Code (or editor X) was
> packaged in Guix and had great support for working with Guile, we could
> also mention it in our manual or in the cookbook.
> 
> Notice I use recommend rather than mandate; these are just
> recommendations that try to be helpful. If it's not helpful to you, you
> are free to select your own tool box and share how it works (via patches
> to the contributing section or a blog post for example).

Of course, but it's limiting because there's no other recommendation than that.
Everything is built around it with no sensibility to any other approach.

Many times I've been answered how to solve my problems using emacs and a big
part of this conversation evolved in that direction, proposing technological
solutions to human problems in emacs, and only for emacs, ignoring the fact
that many guix users are not emacs users and also that technology is not the
root issue of this.

If you have a hammer everything look like nails I guess, and we are
programmers, there's nothing shameful about that, but if we really want to be
welcoming we have to be more than just programmers. Maybe that's something not
all of us should do, but some. I don't know.

Further than that. I'll try to summarize my views on this because I think we
diverged a lot in that direction and it would be a shame to miss this
opportunity to be more welcoming.


## Boring stuff coming, you have been warned

The technology itself is not a real deal most of the times. Sometimes it can
be: should I recompile the project? How do I configure the development
environment? Why my setup has to be a little bit worse if I'm not working with
emacs? How do I contribute my patch with the email provider of my choice? Can I
just paste the patch in the body of the email? Maybe attach it? Which one is
better? One patch per email? Maybe I'm bothering people asking the same thing
over and over again?

Most of those are a matter of getting used to some things that might be hard at
the beginning. I'm sure Katherine, who started this thread is not really
limited in a technical level, as I am not. We might be limited in the amount of
time needed to get used to these things and we don't want to bother
maintainers and commiters with stupid errors we feel like we are committing
over and over again because we don't have a solid reference for some of these
things. Examples of missing pieces of information:

> If you can't use `git send-mail` for a reason you can do this and that and
> that instead.

> If you are not an emacs user you can try this and that. (*probably this is
> something we, non-emacs users, should write*)

Example of a good way to do it, (maybe it's missing a reference in the docs):

https://guix.gnu.org/en/blog/2021/the-big-change/

Political/management decisions often more complex to deal with. Changelog style
is, in my opinion, useless, but it's not hard to follow if there are good
guides on how to do it well. There are other changes in the way packages are
described that are hard to follow too. Just copying what other people did is
not enough, probably because we don't feel like we can control what we are
doing. It's some kind of a trial and error process that always ends up in the
hands of the commiter or maintainer that receives our patches.

My take is: *check what other packages/commits do* is not a real answer. The
same way reading some English is not enough to write English yourself
comfortably. We need guidance or clearly written stuff that is *easy* to find.
Most of these questions are answered in the mailing list, the same way I think
Liliana very well explained how Changelog commits have to be done, but it's not
written in Guix itself (there's a link in the manual) by Guix and *for* Guix.

I would prefer to use other kind of tooling. Sourcehut is interesting as it
provides a way to keep the same email based approach we use, but with some
extra goodies, but I'm also OK with what we currently have. So that's not a big
deal for me at this point. I can say I'm starting to get used.

If we had a *very clear* guide, that would be way better for contributors. Not
just about Guix, but about all those other things that happen around. And I
don't mean a copy/paste tuto, but something were decisions are explained with
the goals they have.

(As a note, the GNU Standard for Changelog commit messages has some examples
that are way more verbose than the ones we have in Guix. IMHO those have a lot
of sense, the commit messages we do in Guix most of the times don't.)


The final point I would like to insist on is the contribution experience. I
don't really know how the issue system works as a whole. We have issues that
are ages old, and new issues are opened every single day... This *must* be
superfrustrating for maintainers. Currently I use https://issues.guix.gnu.org/
to track some of them, but it's not easy to follow at all.

You have been talking about mumi a lot in this thread. To be honest with you, I
had a hard time trying to learn what it actually is and how to start using it
and I even gave up with it. That's not a good contribution experience. I just
felt like just sending a couple of patches from time to time is enough for me
and I can manually use email for that.

Also as I already said, there are many patches that are forgotten forever, I
contributed with a build-system more than half a year ago and I got no answer
from anyone. It's a change that doesn't affect the core of guix at all, and
it's better merged than not. It could just be merged and keep an eye on how
does it work in the wild and wait for other contributions. It's a little bit
frustrating, and as I already mentioned it also has to be frustrating for that
maintainer that would love to review what I sent and has no time for it because
of all the patches that should be corrected because stupid problems people
commited because the process is not really clear.

I don't know.

I'd also love to be a commiter, help a little bit more, but I think there's a
knowledge barrier I feel I will never cross. I'm quite comfortable doing many
things, but I think I can't learn anything else. The only ray of hope I have is
the article series Unmatched Paren is sharing in the Guix blog (thanks).

It's also discouraging to have questions and never get answers for them. For
things that should work and are broken. It gives you the feeling that
everything is fragile, and there's no way to fix. The only computer I work on
is Guix, I am invested on this, but sometimes for work reasons I feel I would
need to abandon it, as many things that should just work are basically useless
and I can't fix, even if I'd love to. Example:

> I just want to build a program for arm-none-eabi, for gods sake! Every
> variable is set up properly... What am I missing? What could I possibly be
> missing???

Probably, if we had an easier contribution process, these secondary problems
would just become slight inconveniences, which is what they often are, but some
days they hit really hard.

This is what it feels like. Sometimes.

Most of the times, though, it feels Guix is really awesome, that you people are
amazing and I'm really happy to be part of this.

I can only be thankful of being a tiny part of this amazing piece of software
and all I've learned in the process.

We can do better, but that's no reason to forget all the good things we have.

Cheers,
Ekaitz