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

[Katherine Cox-Buday <cox.katherine.e@gmail.com>]

Summary of my conclusions:

1. We should use sourcehut or continue to improve mumi
    - QA status should be visable from a patch's page
    - It should be possible to interact with the issue through the page

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

3. We should reify a way for Guix, the project, to measure, and track 
progress,
    against long-term goals. Particularly when they're social and not 
strictly
    technical.

On 8/28/23 4:17 AM, Simon Tournier wrote:
 > Hi Katherine,
 >
 > On Fri, 25 Aug 2023 at 19:02, Katherine Cox-Buday 
<cox.katherine.e@gmail.com> wrote:
 >
 >> I think there's utility in distinguishing between familiarity and
 >> eliminating toil. I think it was incorrect of me to suggest forming
 >> habits in my original message. I think it's better to focus on
 >> eliminating toil so that whatever workflow remains can more easily be
 >> habituated.
 >
 > Since I am French, I am good as moaner and I would like to avoid the
 > ramblings of some grumble party. :-)
 >
 > I agree with you that it is important to reflect ourselves about our
 > practises and we need to be critical about what does not suit us.
 >
 > 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.

[I'm usually starting here]

   4. Run `./pre-inst-env guix refresh --list-dependent <package>`
   5. Create a git worktree for your patch
   6. Run `./bootstrap`, then `./configure --localstatedir=/var 
--sysconfdir=/etc`
   7. Run `make`
   8. Make your changes
   9. Build to ensure your changes are workable.
   10. Try and determine how your changes should be factored into individual
       commits (sometimes it's not always so clear when changing two 
things might
       need to be done atomically).
   11. Try and get each commit message close to correct and commit.
   12. Run `guix lint`
   13. Run `guix style` (this is still in the manual although I have since
       learned this is not actually advisable).
   14. Review the changes these tools have made, and fix things.
   15. Run `guix build --rounds=2 <package>` to check for idempotency.
   16. Run `make` to ensure you didn't break anything elsewhere in Guix.
   17. Run `guix size` to ensure the closure isn't becoming bloated.
   18. Build all the packages that depend on this package.
   19. Run `guix pull --url=/path/to/your/checkout 
--profile=/tmp/guix.master` to
       ensure you didn't break Guix in a different way.
   20. Run `git format-patch -1 --cover-letter [--reroll-count]`
   21. Run `./pre-inst-env ./etc/teams.scm cc-members <patch>` to get 
the CC flags for Git
   22. Remember that if you're sending multiple patches, an email first 
has to be
       sent to `guix-patches@gnu.org` to get an ID, and then...
   23. Run `git send-email --to guix-patches <patches> <CC flags>`

I view steps 1-10 as pretty standard "development" steps common to most
projects, although 11 compounds the effort in 10.

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.

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. 
The extra
step to get a debbugs ID is annoying.

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.
   14. Wait for CI to tell you if anything is wrong.

So now that I've enumerated the steps, compared them to contributing to 
projects
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".

   As I understand it, we're continuing to make progress in having a nice CI
   pipeline (i.e. https://qa.guix.gnu.org), so maybe I need to read more 
about
   that. 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.

- 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. It (1) notices you've pushed a 
branch
   when you visit the website and suggests opening a PR with a link. (2) 
Submits
   the PR with appropriate settings (3) Recommends reviewers which you 
can add
   after the fact.

   Also, this workflow doesn't change whether you have one commit or two 
in your
   branch, and it doesn't doesn't change when you need to submit 
follow-ups (e.g.
   changing flags on `git format-patch`).

   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 would probably have to learn more about it before making this 
assertion, but
   it also seems like any information it provides can be fetched from 
git. And
   when it comes to the steps to contributing, the answer is "memorize these
   flags", but when it comes to retrieving this information, the answer 
is "this
   is easier". I'm not sure about this is a fair comparison, but it might be
   something to collectively reflect on.

- 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 could be a starting point for something going to etc/ similarly as
 > etc/committer.scm or etc/teams.scm.  Well, etc/guix-install.sh somehow
 > started as a script for eliminating toil – it looks similar as the
 > situation: all the steps are described in the manual but they are too
 > many effort for installing and most newcomer were dropping before
 > completing.

Yeah, after sitting with this a bit, I think this, or new Guix 
sub-commands, is
probably a good path forward. The way I'm thinking about this is that we 
need to
lift the individual steps into higher-order activities and have the 
higher-order
activities encapsulate flags and whatnot.

Thinking about all of this, I am reminded of this[1] picture. If we want 
more
contributions to Guix, we have to do better at providing equitable ways 
to work.
Focusing on this benefits everyone because it makes contributing easier for
everyone.

If you're so inclined, for a bit of fun, and as a crude way of simulating
compromised executive functioning, imagine that between each of the 
steps above,
a year passes. And reflect on what it would be like to gather the energy to
start the process of starting a contribution of some kind, let alone 
follow it
through to completion.

And finally, I'm wondering how Guix, the project, tracks metrics on 
these kinds
of things? If we wanted to make contributing easier, that's something we 
have to
create a metric for and track over time. Is there a precedent for this 
in Guix?

[1] 
https://external-content.duckduckgo.com/iu/?u=https%3A%2F%2Fwww.lrhsd.org%2Fcms%2Flib%2FNJ01000316%2FCentricity%2FDomain%2F1239%2FEquity%2520graphic.jpg&f=1&nofb=1&ipt=507d2c18cd2643bcb9ba2a67a13dc86d1926301212aaf04bcefc3d17571f982e&ipo=images