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

[Simon Tournier]

Hi Ricardo, all,

On Fri, 08 Sep 2023 at 17:27, Ricardo Wurmus <rekado@elephly.net> wrote:

> Now, this is no longer a problem for me because I’ve been writing so
> many commit messages over the years (and because I no longer try to
> adhere to some poorly specified format), but it *is* a problem for
> people that I’ve mentored.

Well, from my point of view, you cannot know if another way to write
commit message format would not be a problem either. :-)

I think commit message are for communicating and communication implies
norms and norms are by definition excluding.

Once we have said that, we are locked. :-)

Well, somehow, I think Vagrant’s words [1] captures the situation.
Somehow, I am paraphrasing using my own words. ;-)

IMHO, the questions is not about pros and cons for some non well-defined
ChangeLog-like commit format message, but what are the values of the
commit messages for the project?

If we answer there is no value, then yeah we could use full-free form
commit message.  Somehow, that’s what the Julia language is doing [2].

If we answer there is a value, can we say explicitly which one?  Or
which ones?  And what could be the format that captures these values.

For me, the value is first to have a common structure (uniformity
similar as coding style), and this common structure then 1. allows to
easily navigate through the history and 2. eases the reading for the
people who knows the structure.

And second the value is something like « it forces some discipline on me
by having me review my changes in details and write out what I did » as
Maxim is describing in [3].

However, this structure comes with friction. It is not possible to have
a structure (norm) which is fully without friction.

The question is thus: what is the structure that maximize the value and
minimize the friction?  And the optimum is person-dependant.

I think we have a consensus about the complexity for contributing.  From
my point of view, all the “cognitive complexity” are not equal.  Some
cognitive loads are totally useless and just pure friction – the number
of steps for checking and submitting for example – and it brings no
value at all for the project.  Other, as commit message format, also
leads to some friction but it also brings value for the project.

For these latter case, the improvement is not clear for me.


Cheers,
simon


1: Re: How can we decrease the cognitive overhead for contributors?
Vagrant Cascadian <vagrant@debian.org>
Wed, 06 Sep 2023 10:52:45 -0700
id:87h6o7mbo2.fsf@wireframe
https://lists.gnu.org/archive/html/guix-devel/2023-09
https://yhetil.org/guix/87h6o7mbo2.fsf@wireframe

2:
https://github.com/JuliaLang/julia/commit/70000ac7c3d5d5f21e42555cdf99e699a246f8ec

3: Re: How can we decrease the cognitive overhead for contributors?
Maxim Cournoyer <maxim.cournoyer@gmail.com>
Mon, 28 Aug 2023 23:00:00 -0400
id:874jkift8v.fsf@gmail.com
https://lists.gnu.org/archive/html/guix-devel/2023-08
https://yhetil.org/guix/874jkift8v.fsf@gmail.com