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.katherin...@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-patc...@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
