[vtk-developers] Commit log guidelines

[Ben Boeckel]

[ Sorry for the slight necro-thread; cherry-picking interesting threads
  after vacation. ]

On Tue, May 17, 2016 at 17:21:33 -0400, Sean McBride wrote:
> What problem are we solving here?  Have people found looking through
> history that previous commit messages are not useful/helpful somehow?
> Honest questions.

Yes, I've dug through history when working on things and found commit
messages that were less than helpful.

Tracking down bugs and finding out that the code was added 4 months ago
in a commit with the message "try to fix build on $dashboard" with no
mention of what the problem it was trying to fix was in the first place
is…not the greatest use of my time when 10 more seconds putting some
care into the commit message in the first place would have saved me lots
of time. Of course, such a commit should be squashed, but if it's going
to exist…

And even for the author, going back to a commit from 4 months ago, you
can more easily remember things if you put reminders of what you did in
the commit message when people come and ask you "so about that problem
$dashboard had…".

Basically, be kind to your future self; it is probably more forgetful
than you are ;) .

> I especially find 3, 4, and 5 aren't solving problems, and
> unnecessarily OCD.  2 and even 6 I find overly restrictive.  Are we
> reading commit messages on 1970s CRTs? :)

Meh, I don't do the capitalization thing because it isn't a sentence,
but I rather prefer the "area: summary" style so that you can easily see
where things are changing (and the capitalization of the summary bit
looks weird to me). Here's a --oneline --no-merges log of buildbot from
a random section:

    dd92d2a vtkm: fix autocommand
    d7d539f schedulers: handle 'info' not existing
    c312a6c schedulers: log that setting the status failed
    d5351dc inotify: fix typo
    a9fa6d7 schedulers: log about the pending status
    d42ef82 inotify: add a cdash link to the CI status
    c0b7c6e inotify: comment that the change has been queued
    59bbb81 schedulers: set the pending status on the right project
    56870a1 gitlab: bail if there is no source_project_id
    0e55ce1 gitlab: put status on source project
    cba5726 changes: set source_project_id in integration branches
    ef81a0d trey: update the cmake

Skimming this, you can tell what was changed and what it affected. Of
course, this works best with proper commit etiquette in the first
place.

> I think the most important guideline is to write messages that:
>  - help reviewers understand the what, why, and how.
>  - help our future selves when regressing through history.

This is certainly a good start.

--Ben