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

[Simon Tournier]

Hi,

On Mon, 28 Aug 2023 at 23:00, Maxim Cournoyer <maxim.cournoyer@gmail.com> wrote:

>> If someone has use cases for the ChangeLog commits, I'd like to hear
>> them. Maybe there is something that can't be achieved with git history
>> without ChangeLogs, but I can't think of anything. Someone mentioned
>> grepping the git log with them, but I think the same thing can be done
>> with git log and git blame regardless of the commit message format.
>
> I used to think the same about ChangeLogs style commit messages, but I
> have to admit that it forces some discipline on me by having me review
> my changes in details and write out what I did.  It'll sometimes expose
> something that'd be better kept in a separate commit, or something I did
> and forgot about in the early development, that should be dropped.
>
> There's also no stopping you adding a more conventional rationale as a
> paragraph between the topic and the ChangeLog content (which should
> appear at the bottom of the commit message).

I agree with Maxim. :-)

At first, I found weird the ChangeLog commit format and now it forces
some discipline on me that I find that beneficial.

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?

Even, it is that format (discipline) which makes “git log” efficient,
IMHO.

As an exercise, try to find the last 5 commits modifying the procedure
’haskell-build’,

        $ git log --format="%h %s" --grep=haskell-build -5
        2c0537d374 gnu: idris: Adapt to changed haskell-build-system.
        dc3e22f4d5 build: haskell-build-system: Build static executables by 
default.
        4bb40b098d build-system: haskell: Drop default "static" output.
        9262c14d73 build: haskell-build-system: Remove unused linker flags.
        39c97cf3d0 build: haskell-build-system: Process all transitive 
dependencies.

Cheers,
simon