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

[Giovanni Biscuolo]

Hello Katherine,

thank you for having summarized (part of) this thread in a list of
actionable tasks

now Someone™ have the chance to decrease the cognitive overhead for
contributors by _increasing_ her cognitive overhead to sort out and
complete each task

as a general comment, it seems to me that you put very much attention to
the process of contributing v1 of a patch but you underestimate the
cognitive overhead of the collective patch reviewing process and
committing to Guix proper process

AFAIU, observing what is happening in Guix since 2019, what is actually
critical for Guix is _not_ the cognitive overhead needed to send a patch
to guix-devel, but what comes after and _around_.

last but not least, to be fair we should see at what other distribution
(not single software projects) are doing for their contributing process:
I know a little about Debian and in my experience it's far easier to
contribute to Guix than to Debian (but I know little, I emphasize)

Katherine Cox-Buday <cox.katherine.e@gmail.com> writes:

> Summary of my conclusions:
>
> 1. We should use sourcehut or continue to improve mumi

Please forgive me if I insist, but the one and _only_ benefit of using
SourceHut is the web-UI /helper/ to prepare an email message to send,
it's "just" a web-UI version of the "git format-patch" CLI; the rest of
the "patch management workflow" is email **and** CLI (git am) based;
it's documented.

Furthermore, users that are comfortable with the SourceHut web UI are
free to use that as their personal working repo, there is no need for
Guix to use a SourceHut remote as the official one.

>     - QA status should be visable from a patch's page

On mumi web interface, in each issue page related to a patch, there is a
"badge" linking to the QA status for that patch, right below the issue
title; i.e.:

https://issues.guix.gnu.org/65694

have a link to https://qa.guix.gnu.org/issue/65694

QA (and relates services, like data.qa) is a great project that could
greatly improve current situation when completed!

>     - It should be possible to interact with the issue through the
>  page

I don't exactly understand: what do you mean with "interact"?

...and what page?  https://issues.guix.gnu.org/ or
https://qa.guix.gnu.org/issue/65694 (or any other issue)

> 2. We should create scripts/sub-commands to lift contribution activities 
> into
>     higher-order concepts:
>     - Prepare a new submission
>     - Run pre-checks on a submission
>     - Submit a patch
>     - Status of patch

AFAIU you already use some of this "lifting" scripts od commands: can
you please send patches so thay could possibly be included in Guix
proper or in some section of the Cookbook?

[...]

> On 8/28/23 4:17 AM, Simon Tournier wrote:

[...]

>  > In order to be pragmatical and list actionable items, could you
>  > specifically list what you consider as a toil or cognitive overhead?
>  > Maybe you could share your script helping you.
>
> Yes, great point! Let's try to distill all this conversation down into the
> salient points and see if we can't agree on some actionable items.
>
> Here's my understanding of the process to contribute a patch:
>
>    1. Check out main, and run `./bootstrap`, then `./configure 
> --localstatedir=/var --sysconfdir=/etc`
>    2. Run `make`
>    3. You need to determine whether the change can be targeted against 
> main or
>       needs to target a feature branch, so you go read about that.

[...]

> In other projects I've worked with, steps 12-19 are commonly done in a CI
> pipeline, and courteous people will try to save CI resources by running 
> these
> steps locally first using some kind of environment identical to what CI runs
> (sometimes a container is used for this. I think Guix has better options!).
> Sometimes this is not feasible due to asymmetric resources. But having the
> option to let CI manage this process is very nice.

AFAIU this is where https://qa.guix.gnu.org/ is intended to help, but
now is not working as intended AFAIU

> For me, steps 20-23 are bothersome. There's a lot of "if" statements 
> that lead
> to branching operations, and a lot of commands and flags to get
> right.

oh yes, CLI is a cognitive overhead sometimes, so we need better
interfaces, some have found them

actually, point 21 "Run `./pre-inst-env ./etc/teams.scm cc-members
<patch>` to get the CC flags for Git" is bothersome and we should find a
way to better integrate that in "git format-patch" (so that will be
automatically used in all the git interfaces we use)

> The extra step to get a debbugs ID is annoying.

have you tried mumi CLI with the new feature?

> If I compare this workflow to the workflow of other contributions I make:
>
>    1-10 as usual
>    11. Write a more commonly accepted commit message with no special 
> formatting.
>    12. Run `git push` (subsequent changes are still just `git push`).
>    13. Go to forge website, click button to open a pull-request.

Forgive me if I insist: that forge site is _not_ SourceHut

Second: each forge web site have a custom (not standard) way to manage
pull-requests.

Third: git have a pull-request mechanism [1] that could _easily_ be
integrated in each and every forge, allowing projects to use
/interoperable/ email based pull-request workflows if they want to.

[...]

> I don't find difficult, and reflected on the difference for awhile, I 
> think, at
> least for me, the highest friction comes from:
>
> - Steps 11-19, or (to assign it a name for easier reference) the "CI
> steps".

OK: AFAIU https://qa.guix.gnu.org/ is _the_ answer, so we need more
contributors to that project

...and this means more cognitive overhead for Someone™ :-)

[...]

> If we wanted to encourage contributors to run "CI steps" 
> locally before
>    submitting, maybe this should be another `guix` sub-command? `guix 
> pre-check`
>    or something? I know there is a potential contributor who had this 
> idea first
>    who would want to hack on this.

Having such a sub-command maybe could help, maybe not, because IMO the
core and most cognitive challenging steps of all "CI steps" are not if
builds are done locally or not but (in order of importance):

1. having patches reviewed by humans, the "not automatable" part because
Someone™ have to understand the _meaning_ of the patch and verify it
conforms to the coding standards of the project, including "changelog
style" commit messages;

2. understanding why build derivation fail when it fails.

This is real cognitive overhead and this cannot be automated.

> - Steps 19-23, or the "manage patch" steps.
>
>    I think an insight here is that the big button on forges is actually 
> a program
>    removing the mental overhead for you.

On the "web forges" vs "email based" patch workflow management I've said
enough in other messages in this thread, here I just want to add
(repeat) this: please do not only consider the mental overhead of
potential contributors for "managing patches", also consider the mental
overhead for patch reviewers; I've read many articles from professional
patch reviewers that perfectly explains the great advanteges of using an
email based workflow

[...]

>    I also don't usually have to worry nearly as much about crafting a commit
>    message. So long as the title is under a character limit, and the body is
>    helpful, it's OK. I think what bothers me most about the GNU changelog
>    messages is that it's the worst of both spoken language and programming
>    languages: there's an expectation of structure, but no grammar I can 
> parse
>    against, and it's free-form.

I'm sorry that the GNU policy about commit messages bothers you (on the
contrary it makes me happy); please consider that thai is /just/ one of
the policies of the Guix project: code of conduct, coding standards,
others?

[...]

> - Having multiple places to manage aspects of my patch
>
>    In a web-forge, I generally have a URL I can go to and see everything 
> about my
>    patch. I think we have that with https://issues.guix.gnu.org with two
>    exceptions: (1) QA is a click away, or if you're using email, you're 
> not even
>    aware that there's a QA process failing (2) If you're not using email,
>    context-switching between this page and email to respond.

it's "just" an _interface_ issue

[...]

Happy hacking! Gio'


[1] https://www.git-scm.com/docs/git-request-pull

-- 
Giovanni Biscuolo

Xelera IT Infrastructures

signature.asc
Description: PGP signature