[vtk-developers] Commit log guidelines

[Marcus D. Hanwell]

On Tue, May 17, 2016 at 5:21 PM, Sean McBride <sean at rogue-research.com> wrote:
> On Tue, 17 May 2016 12:15:22 -0400, Utkarsh Ayachit said:
>
>>Folks,
>>
>>I recently came across this: http://chris.beams.io/posts/git-commit/
>>
>>Any thoughts on adopting this as a style guide? The rules are:
>>
>>1. Separate subject from body with a blank line
>>2. Limit the subject line to 50 characters
>>3. Capitalize the subject line
>>4. Do not end the subject line with a period
>>5. Use the imperative mood in the subject line
>>6. Wrap the body at 72 characters
>>7. Use the body to explain what and why vs. how
>>
>>I think (7) really brings it home, although I wonder if a short "how"
>>can also be included.
>
> What problem are we solving here?  Have people found looking through history that previous commit messages are not useful/helpful somehow?  Honest questions.

I scan through commit messages for various reasons, and appreciate
good short email subject style commit subjects. They help me decide if
I want to look more deeply at that commit, or help me compile a list
of additional features in a given period.
>
> 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? :)

I don't find capitalizing the first word in a sentence OCD, and will
ask people to do that, same with not needing a period, small things
but they can add to readability. I don't want to get the grammar
police out, but I don't find this OCD personally.
>
> 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.
>
I think these guidelines help in both those regards, and offer a
reasonably consistent style. I am not sure I have always stuck to all
of these points, but in general this is roughly how I try to structure
my commit messages. This seems to be something that has been adopted
across a number of other projects.