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

[MSavoritias]

Simon Tournier <zimon.toutoune@gmail.com> writes:

> 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:
>
> 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.
>
>
> 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,
>
> $ 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.
>
>
> And because there is some variation with the commit message format,
> these are not all the updates of VLC,
>
> $ 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].
>
> 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.
>

Bear in mind that Sourcehut accepts patches without an account and there
is forgefed https://forgefed.org/ for forges federation. which forgejo
has support https://forgejo.org/

MSavoritias

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