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

[wolf <wolf@wolfsden.cz>]

[-- Attachment #1: Type: text/plain, Size: 11047 bytes --]

On 2023-09-05 16:01:17 +0200, Simon Tournier wrote:
> 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!

I personally am glad it is not there, since I never (in ~9 months toying with
Guix) had all the checks pass on the clear master.  There are always one or two
failing tests.

But I guess this was supposed to be taken as "run make check' and make sure
nothing new is broken".  Is there a command for that?

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

-- 
There are only two hard things in Computer Science:
cache invalidation, naming things and off-by-one errors.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]