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

[Ekaitz Zarraga <ekaitz@elenq.tech>]

 
> I think a lot of this discussion is stuck on what is better web or
> email. Where it doesn't have to be.
> 
> What we instead need to do is acknowledge that some people like the web
> approach.
> 
> And accommodate them so we can have guix used by more people. Simple as that :D


Exactly.
An option is to make some kind of user-story based documentation might help?

For example:

------
- If you are used to a web-based git forge such as gitlab or github, Guix's approach
to collaboration might seem a little bit hard at the beginning.
Guix uses an email based approach, like many other GNU projects do. Email based
approach relies on sending commits as patches that can be later applied by commiters
and maintainers. Thee patches are sent via email, in plain text, instead of using a
website for a Pull- or Merge- Request.

You don't have to worry about the format of the emails, as git is able to generate
them for you:

   $ git commit ...
   $ git format-patch ...

If you configure git properly (link to how to do it), git can send those emails to
guix automatically (see Using Git Send Mail). If you prefer, you can copy the content
of the file `format-patch` generates in a plain text email, or attach it and send it to
`guix-patches`.

When that email is received a bug report will be opened in guix's issue system, where
you can further discuss, as you would do in any other issue board or merge- or pull-
-request discussion. The discussion is available at `URL` and looks like `screenshot`.

If you want to share a series of patches...
------

Something like that (done with more care and attention than what I just did), might
help newcomers. It's mostly the same our documentation says, but our documentation
currently (I think) relies too much on the people knowing what everything means.

Maybe a deeper contribution guide might be an interesting thing to write down...
Also including some introduction to the internals and how to write a build-system...
Stuff like that is always useful.
It has to be properly maintained though, but even if it is out of date, it's still
a valuable resource to have some info about the *concepts*. (we can always put the
date of the latest change and a note: this documentation is designed to explain the
concepts, the specific details might be out of date, but the concepts remain).

Or something, I don't know. But I'm open to try it :)


The case of the Changelog commits has been discussed and its important too.
We need to be able to make contributors learn how much they need to write down in
the commit messages. I tend to write too much, and I don't think any of my patches
have been applied without changes in the commit message.

For example, in guix we often do (I just invented the name): 

gnu: Add lolo

* gnu/packages/engineering.scm(lolo): New variable.

Is that enough to describe the addition of a new package? If you know what you are
looking for it might be, but it looks like an automatism commiters have that is not
communicated properly. What if there's something in a `let` i changed? I have to list
that too? What if...?

Some help on that might be useful. And also, explaining how important it is to follow
the jargon we use in the commit messages. Or how long should our explanations be...
Just to help people don't feel overwhelmed about it, nothing more than that (and 
nothing less!).

I don't know if this adds anything new to the conversation.

Cheers!