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

[Christopher Baines]

Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:

> 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":
>
> * gnu/packages/file.scm (package-symbol)
> [arguments] <#:phases>: New patch-paths phase.
>
>
> It could also have been:
>
> * gnu/packages/file.scm (package-symbol) [arguments]: Add patch-paths
> phase.
>
> 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).

I think I have a similar feeling to Vagrant, and on whether this
matters, I think it matters a lot.

In terms of encouraging people to contribute to Guix, we want the
documentation to set people up for success, or at least feeling like
they're doing things correctly.

The docs say:

  Please write commit logs in the ChangeLog format (see Change Logs in
  GNU Coding Standards); you can check the commit history for examples.

Which is expecting a lot of people who haven't encountered this
before. My view on this is that asking people to perform this task that
isn't very well documented or defined, and which people reviewing and
committing the changes will comment on or revise (maybe to be
objectively better, or maybe just in their own style) discourages people
to continue to contribute, especially those that care more about not
making mistakes/getting things right, or that lack confidence.

I'm indifferent about how we write the commit messages, I'm strongly in
favour of the expectations being clear and documented so that if people
new to the project want to attempt to write a good commit message,
they're setup for success with good documentation, and if something they
write can be improved, there should be some bit of documentation you can
point them to.

signature.asc
Description: PGP signature