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

[kiasoc5]

Hello,

On 2023-09-06 04:49, Maxim Cournoyer wrote:
> Hi Katherine,
>
> Katherine Cox-Buday <cox.katherine.e@gmail.com> writes:
>
> > On 9/5/23 10:01 AM, Simon Tournier wrote:
> >
> > > Well, somehow, I consider the commit message format similarly as 
> > > coding
> > > style.  We can discuss which one is better than the other when at the
> > > end it only reflects some artificial preferences and for the sake of 
> > > any
> > > project one needs to be arbitrarily picked.  Why not ChangeLog?
> >
> > The distinction I draw is that I can usually run a linter against a
> > coding style.
> >
> > I don't care very much what the standard for commit messages is other
> > than if it has an expectation of structure, I be able to run a tool to
> > tell me if it's wrong.
> >
> > In other words, the overhead isn't "I don't like this standard", it's
> > "I can't find a way to reliably adhere to the standard".
>
> 'git log' should provide ample examples.  The format is not strict, and
> it doesn't matter overly as long as it conveys a summary of the changes
> accurately; it is meant for us humans.  The format is described
> summarily in the GNU Standards document; to read it, you can run:
>
>   guix shell standards info-reader -- info '(standards) ChangeLog'

Would be good to distill these conversations to the manual.

It would also be nice to add a section to the cookbook on explaining the 
parts of the commit message as it relates to Guix as a quick reference 
instead of grepping around for several wordings of the same action. From 
what I remember there's at least these parts to mention:

- including the package name and version on upgrades
- any changes to phases
- any changes to new input style, G-expressions, removal of trailing #t