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

[Vagrant Cascadian <vagrant@debian.org>]

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

On 2023-09-06, Liliana Marie Prikler wrote:
> Am Dienstag, dem 05.09.2023 um 19:41 -0400 schrieb brian
>> ‘* foo/bar.scm new-package (inputs): add input’
>> 
>> stuff. I literally can never remember this format, no matter how many
>> times I do it. I'm reasonably sure square brackes go in there some
>> where. It can take me quite a while to put together all that stuff,
>> even with magit's help.
> It's 
>
> * file (variable)[field]<even closer selector>{do you need 4 levels?}

Honestly, not knowing the difference between a variable and field and
selector... this comment is of little help to me.

I always get tripped up with phases, modify-phases, etc. as there seem
to be potentially four or more levels deep in some common code
patterns... for example, a recent commit mentioning phases:

commit c14c25b4fb625c2a5b9512618b3eb17ff15f7e71

    gnu: go-github-com-tdewolff-minify-v2: Regenerate hash.

    * gnu/packages/golang.scm (go-github-com-tdewolff-minify-v2)[#:phases]: Add
    phase 'regenerate-hash.
...
diff --git a/gnu/packages/golang.scm b/gnu/packages/golang.scm
index 44953d6111..3c486c4121 100644
--- a/gnu/packages/golang.scm
+++ b/gnu/packages/golang.scm
@@ -3685,11 +3685,24 @@ (define-public go-github-com-tdewolff-minify-v2
                 "0h006wpfkl0ls0skqxblwcanrhmphgq5q0ii26l2ayh7s99cgmy3"))))
     (build-system go-build-system)
     (arguments
-     (list #:import-path "github.com/tdewolff/minify/v2"))
+     (list #:import-path "github.com/tdewolff/minify/v2"
+           #:phases
+           #~(modify-phases %standard-phases
+               (add-after 'unpack 'regenerate-hash
...

Why is it not more like:

    * gnu/packages/golang.scm
    (go-github-com-tdewolff-minify-v2)[arguments][phases][modify-phases]:
    Add 'regenerate-hash.

Honestly, that *seems* ridiculous to me, but I do not understand *why*
based on the comment above or other patterns I have observed in the
wild.

My inclination would be:

    (go-github-com-tdewolff-minify-v2)[arguments]: Add phase 'regenerate-hash.

What goes in the square brackets? How many levels deep? Do I put
something in the prose of the comment or in square brackets?

For me, all this is only from observing many commits, submitting a few
patches, getting some good feedback, but really at the end of the day I
am just cargo-culting...

I have been submitting patches, and even pushing commits to guix for
several years now, and it is still quite unclear to me.

I can wing it just fine, and am able to submit imperfect patches and
have patience for reviews and suggestions and have the resources to
respond (at least, most of the time)...

I can see how really not wanting to iterate with N back-and-forth
discussions in review could hinder someone with a less flexible
schedule, especially if there are no other significant changes to the
patch... it could get demotivating.

It is obviously tricky, as sometimes people need back-and-forth
discussion to learn... though maybe they would rather focus their
limited energy learning how to program, a new language (guile), or just
learning how guix works in practice.

For some people, they might just not have the time or emotional energy
and just prefer to keep their changes in their local branch so they can
move on to the next thing that actually is motivating their work,
tinkering, play, etc. or move on to something else entirely which is
more rewarding, such as gardening...

This is not to say there is no value in the current commit message
format norms. Obviously some people have described the value it has for
them...

One value may be contextually dependent and sometimes at odds with other
values.


live well,
  vagrant

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