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

[Simon Tournier]

Hi,

At some point, I sympathize.

On Wed, 23 Aug 2023 at 10:25, Katherine Cox-Buday <cox.katherine.e@gmail.com> 
wrote:

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

I agree that Debbugs is not handy at all for submitting patches.  Send
the cover letter, wait, refresh email, wait, refresh email, loop until
an issue number is assigned, and then send the series.

Well, Debbugs is an issue tracking system and not a patch tracking
system, from my understanding.  And thus this annoyance is not about
email-based workflow.  It is just about using Debbugs for tracking
patches, IMHO.


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

Reduce friction for making contributions?  Yes, we all want that, I
guess.  The question is how?  What is the right balance between the
change of habits and the satisfaction of people used to these habits?

Well, from my point of view, we are using here the term “contribution”
as it was one homogeneous thing.  Instead, I think the term refers to a
range with a gradual complexity.  And the improvements or tools maybe
also need to be gradual depending on this range.

For example, a two-line patch trivially updating one package is not the
same contribution as several-to-many two-line patches more some package
additions for updating all the R ecosystem.  And that’s not the same as
rewriting the Python build system or as packaging the last version
TensorFlow.

The cognitive overhead for these 3 contributions is not the same.
Therefore, the way to reduce the friction will not be the same, IMHO.


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

Considering this range of contributions above, I do not see this “make
lots of mistakes”.  Or, let say all the mistakes are not equivalent.

I do not think it is all good or all bad.  From my point of view, all
the contributions are a gift.  I appreciate equally the gift of my
sister who knits a tiny half-done scarf and the gift of my father who
crafts a complete wood-chair.  I empathise both with the busy life of my
sister and with the retired full-of-free-time life of my father.  And I
use or reuse the gifts as I am able to.

Well, no pressure.  Software is done by craftperson who internalizes one
step, then another, and it builds the habits above.  I guess.

I am not avoiding tools.  I think tools as guix style and guix lint
deserve improvements.  Therefore, let open bug report when you notice
wrong or not the expected behaviour.  For example, Vagrant suggested
nice improvements for guix lint and spellchecker.

And QA, partially based on these tools, is also improving a lot.  It
helps to detect mistakes.


> * We could support a managed web-based workflow

Here, I am very doubtful that it would help.

For instance, Debian is based on Gitlab since their switch from Alioth
to Salsa.  It would be interesting to know if this “new” web-based
workflow using Merge Request is increasing the number of submissions
and/or increasing the number of occasional contributors.

Another example is Software Heritage (SWH).  Their web-based workflow is
a Gitlab instance [1].  As an occasional person who deal with the SWH
archive, I am never able to find my way and I just roam on #swh-devel
IRC channel asking for help.

Another example: the channel guix-science [2] based on GitHub.  Well, I
am able to count using one of my hands the number of PRs. ;-) (And I do
not speak about other channels as nonguix)
 
Well, reading the item above about mistake and the item below about
"Guix 'R Us", and maybe I am wrong, somehow I feel that one “cognitive
overhead” is the willing to submit a perfect patch.  Again, maybe I am
wrong, somehow I feel that one part of the issue is a lack of
self-confidence.  Do not take me wrong, I am speaking about submitting a
patch by occasional contributor and not about the personality of person
that I do not personally know. :-)

This “that’s not perfect so I postpone the submission” is something I
often hear by people attending to Café Guix [3].  Hum, I do not know
what we could do differently for reducing this barrier.

The idea of the team Mentor is in this direction but it does not seem
working… :-(

1: https://gitlab.softwareheritage.org/explore
2: https://github.com/guix-science/guix-science
3: https://hpc.guix.info/events/2022/caf%C3%A9-guix/


> * 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?

For sure, I think it’s a very good thing.  In the same direction, I also
find helpful the initiative by Guixers based on London to physically
meet.  We did similar a couple of times in Paris.  Demoing and showing
that nothing is perfect is helping in reducing some barrier.

During lockdown, we (Jérémy and I) did some remote-pair programming [4].
I think this kind of thing could also be a solution because being two
with an appointment and a fixed slot of time, etc. all that keep the
motivation up and help in reducing some barrier.

4: https://10years.guix.gnu.org/video/remote-pair-programming/

For sure, I think that part of the solution is by finding the way to
collaborate.  Somehow, what would be your expectations for contributing
more?  Or for easing your contributions? :-)

Cheers,
simon