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

[Maxim Cournoyer]

Hi Vagrant,

Vagrant Cascadian <vagrant@debian.org> writes:

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

The ChangeLog Style section suggests there should be spaces between the
"markers".  It also says the square brackets should be used to denote a
change made in a conditional code path, so we're abusing the meaning of
it in Guix to just a 'field' (which is, a record field, or slot, for the
<package> record in Guix).  < > is to precise even more the place
modified.  They're just shortcuts to avoid less typing while remaining
readable.

Here's an example in the Guix "dialect":

--8<---------------cut here---------------start------------->8---
* gnu/packages/file.scm (package-symbol)
[arguments] <#:phases>: New patch-paths phase.
--8<---------------cut here---------------end--------------->8---

It could also have been:

--8<---------------cut here---------------start------------->8---
* gnu/packages/file.scm (package-symbol) [arguments]: Add patch-paths
phase.
--8<---------------cut here---------------end--------------->8---

It doesn't really matter, as long as it's clear and you did the exercise
of reviewing the code you touched and writing down the changes summary
for the reviewer (and yourself).
  
-- 
Thanks,
Maxim