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

[MSavoritias]

I dont think we need to compare things here. Of course we should be able
to make lives easier for reviewers and contributors. There is no need
here to compare them. Remember that making lives easier for contributors
will make lives easier for reviewers too after all :) Because more
correct pathces and more people wanting to be involved.
Hence me saying its not a comparison or focusing on one or the
other. But more of the same thing.

As I mentioned in another point in the thread we already have
"non-standard" stuff so that argument doesn't really hold water
here. Non standard stuff being emacs, mumi and a bunch of other stuff
that make submissions tolerable. Or emacs-debbugs.

Also yes "visual" flow helps some people. Nothing wrong with that and we
should encourage that. (Encrourage that by fully supporting it). I mean i am 
trying to use the cli as less as
possible since its a horrible interface.

And yes the gnu commit messages could be improved. Its not like they are
set in stone anyway.

MSavoritias

Giovanni Biscuolo <g@xelera.eu> writes:

> [[PGP Signed Part:Undecided]]
> 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