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

[Simon Tournier]

Hi Katherine,

Thank you for your extensive analysis.  I concur.

On Wed, 30 Aug 2023 at 10:11, Katherine Cox-Buday <cox.katherine.e@gmail.com> 
wrote:

> 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.

That is the most difficult part, IMHO.  Well, what are the long-term
goals? :-)

I am almost sure we will get various answers depending on people.  Let
say the long-term goals of the Guix project are: Liberating, Dependable
and Hackable.  Then how do you give concrete quantities that we can
measure or track?

And it is always difficult, if not impossible, to measure or track some
goals that are not technical but social.  For example, how do you
measure being welcoming or being a safe place for all?

Do not take me wrong, I strongly think we must think again and again on
that point for improving.  It’s just easier to tackle technical bug. :-)


>    11. Try and get each commit message close to correct and commit.

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

Maybe I am doing incorrectly but I have never thought much about that.

For that point #11, from my point of view, it is as with any other
project.  I start by running “git log --grep=” for getting inspiration.

Well, as a rule of thumb, I am doing something like:

--8<---------------cut here---------------start------------->8---
top-module: submodule: one line summary.

Fixes <https://issues.guix.gnu.org/12345>.
Reported by Jane Doe <jane@doe.org>

* path/to/file.scm (variable):[sub-part]: Description of the change.
[otherpart]: Other description.
* path/to/other/file.scm (other-variable): Description.
--8<---------------cut here---------------end--------------->8---

In case of doubt, I am just running “git log --grep=” looking for
similar thing, as said. :-)


>    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.

> 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 instance, I am not seeing “make check”. ;-)  And that omission makes
very clear the cognitive overhead we are speaking about!

Here I see two annoyances:

 1. The number of subcommands and steps.
 2. Each subcommand has a list of options to digest.

Well, CI is helpful here, for sure.  However, it would be helpful to
have a script similar as etc/teams.scm or etc/committer.scm that would
help to run all these steps.

It does not mean that all these steps need to be run before each
submission.  However having a tool would help irregular contributors or
newcomers; it would decrease the cognitive overhead i.e., that overhead
would be pushed to some script and it would reinforce confidence.

Now someone™ needs to implement this script. ;-)


>    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>`

Well, my grey hair are biasing my opinion. ;-)  From my point of view,
the most annoying is #22.

Vagrant suggested [1] to send patches as attachment.  I am not convinced
it will be better.  Well, it will for submitting but will not for
following series.  For instance, let consider:

    [bug#65010] [PATCH 0/8] Misc Python build system improvements
    Lars-Dominik Braun <lars@6xq.net>
    Wed, 02 Aug 2023 12:37:57 +0200
    id:cover.1690972374.git.lars@6xq.net
    https://issues.guix.gnu.org//65010
    https://issues.guix.gnu.org/msgid/cover.1690972374.git.lars@6xq.net
    https://yhetil.org/guix/cover.1690972374.git.lars@6xq.net

then, one will do reply and probably comment one or more patches over
the 8.  Then, it is harder for another person to follow.  For example, I
would have to open the message in order to know that this series adds,

    guix: toml: Add TOML parser.

which could be interesting for Julia.  And I would probably skip all the
series because the subject is about Python build system improvements
that I am necessary following.  However, if I see the subject,

    guix: toml: Add TOML parser.

then I open the message and read it.

Therefore, I do not see any “good” solution for this point #22.  One
idea would be to have a kind of proxy.  We would send the whole series
to an hypothetical guix-contributions@gnu.org and then a bot would send
to guix-patches for getting an ID and that bot would send the series to
that ID, probably adding some X-Debbugs-CC for the submitter (and for
teams).  Bah, too much “would”. :-)


1: https://yhetil.org/guix/87wmx8m5gb.fsf@wireframe
Re: How can we decrease the cognitive overhead for contributors?
Vagrant Cascadian <vagrant@debian.org>
Sat, 02 Sep 2023 18:05:40 -0700
id:87wmx8m5gb.fsf@wireframe
https://lists.gnu.org/archive/html/guix-devel/2023-09


> 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.

This depends on the project and I am not convinced we can rule for #11.

BTW, one strong advantage for this commit message format is that grep
can be exploited.  For some reasons, I am often looking for some past
versions, for example,

--8<---------------cut here---------------start------------->8---
$ git log --pretty="%h %s" | grep Update | grep vlc
8d342711dd gnu: vlc: Update to 3.0.17.4.
5a29cc9ade gnu: vlc: Update to 3.0.17.3.
fb0e5874ec gnu: vlc: Update to 3.0.16.
e2ad110f4c gnu: vlc: Update to 3.0.14.
def314d810 gnu: vlc: Update to 3.0.12.
6ec120b1c7 gnu: vlc: Update to 3.0.11.1.
0bed485a39 gnu: vlc: Update to 3.0.11.
178f1d1f75 gnu: vlc: Update to 3.0.8.
cf40f8e4d7 gnu: vlc: Update to 3.0.7.1.
94f7f9503a gnu: vlc: Update to 3.0.7.
dba326def1 gnu: vlc: Update to 3.0.6.
ea593fe298 gnu: vlc: Update to 3.0.5.
d0e23e3940 gnu: vlc: Update to 3.0.3, and add more inputs.
7627705293 gnu: vlc: Update to 3.0.3, and add more inputs.
f137f84923 gnu: vlc: Update to 2.2.8 [fixes CVE-2017-9300, CVE-2017-10699].
dd13aa90d6 gnu: vlc: Update to 2.2.6.
3bc45ad460 gnu: vlc: Update to 2.2.5.1.
a134cc8e93 gnu: vlc: Update to 2.2.4 [fixes CVE-2016-5108].
c6c86cd7a5 gnu: vlc: Update input Qt to version 5.
9c55bae607 gnu: vlc: Update to 2.2.1.
1a189da0e7 gnu: vlc: Update to 2.2.0.
b9156ccc08 Revert "gnu: vlc: Update to 2.2.0"
ad036bda89 gnu: vlc: Update to 2.2.0
23466647a8 gnu: vlc: Update to 2.1.5.
--8<---------------cut here---------------end--------------->8---

And because there is some variation with the commit message format,
these are not all the updates of VLC,

--8<---------------cut here---------------start------------->8---
$ git log --pretty="%h %s" | grep Update | grep VLC
af74211d98 gnu: VLC: Update to 3.0.18.
5af110868c gnu: VLC: Update to 3.0.10.
091ef8c97e gnu: VLC: Update to 3.0.4.
324c049ff6 gnu: VLC: Update to 3.0.3-1 [fixes CVE-2018-11529].
--8<---------------cut here---------------end--------------->8---

Then “guix time-machine --commit=fb0e5874ec -- shell vlc” and hop I get
3.0.16.  If the commit message format would not be so strict, this would
be impossible and we would need another external tool.


>    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.

To be fair, here you forget one important blocker: having an account to
the forge website.

I do not speak about freedom issues.  Just about the fact to open an
account to the forge website.  For example, let consider this project:

    https://framagit.org/upt/upt

And if I want to contribute with a Merge-Request, I need to open an
account to the Gitlab instance of FramaGit and push my code to this
instance, even if I already have my fork living on my own Git
repository and I have no plan to use this FramaGit forge.


> 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.

I like this way of thinking because it helps to spot some blockers.

Please note that it is not truly about the complexity of the steps but
about how many steps one is able to complete between two interruptions.
Well, it is a well-known issue about task switching [1]. :-)

1: https://en.wikipedia.org/wiki/Task_switching_(psychology)

Cheers,
simon