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

[MSavoritias]

Yep completely agree with all of this.
Personally I dont think its necessery to move to sourcehut but from the
discussions I saw debbugs does seem to become a burden the more time
passes on.

One of the weirdest things for me in guix is how its based on scheme
which is designed to be hacked in place and instead we have so many
complicated steps to do it.

A much more logical thing as bare minimmum is like you said: Have it as
a subcommand in guix. The first thing i tried to do to contribute
personally was to just do a 'guix edit' and edit the package but turns
out not only i cant do it as easy as that but I also need to clone a
repo and run multiple scripts inside a container(?). We should work on
moving as close to a 'guix edit' and 'mumi push' contribution as
possible.

MSavoritias

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

> 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