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

[Ricardo Wurmus]

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

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

I have the same positive view on our faux ChangeLogs commit messages,
though I also would like to have them generated.  The benefit is still
there: I still get to *review* an effective summary of the changes
before pushing or sending them off for review.  But at least I don’t
have to write them myself.

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.

etc/committer.scm and the yasnippets are supposed to alleviate some of
the pain, but I don’t need to think for a long time to come up with a
number of improvements in this area.

> 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).

Yes, this is something that might not be clear to all.  Before the
somewhat mechanical summary you can write a paragraph or two to give
context.

-- 
Ricardo