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

[Liliana Marie Prikler]

Am Mittwoch, dem 06.09.2023 um 10:52 -0700 schrieb Vagrant Cascadian:
> 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.
For one, reusing the same pair of braces is dangerous when you actually
need to split lines, which eventually, of course, you will.  So don't.
Use different pairs.

> 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?
You can use ‘fancy quotes’ in ChangeLogs, which would break scheme
syntax.  So 

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

would be clearer than your suggestion.  Why use [#:phases] then? 
Because people understand it to be a shorthand for
[arguments]<#:phases>, the most common way in which the arguments field
changes.  If you change both that and idk, <#:configure-flags>, you'd
type them out.

> 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.
You won't get N back and forth discussions solely on the format of the
ChangeLog.  If it were just that, the reviewer could just write it on
their own and be done with it; there's typically code changes as well
involved or at the very least undocumented changes that ought to be
documented.


Cheers