[vtk-developers] Commit log guidelines

[Utkarsh Ayachit]

Sean,

A couple of things.
a. These will only be guidelines, a reference to point to developers
when they come up with commit messages; not rules, so no one should
really be forcing anyone to stick to 50/60/ char limit or (3) or (4).
b. I've found myself reviewing 1 line commit logs and hate being a nag
telling people to amend it. Wondered why we don't have a set of
guidelines to refer developers to to help guide them.

A quick google and this is what I found. Thought rather than every
reviewer suggesting different styles for commit logs when guiding
developers, it would be better if we had a short list of agreed upon
guidelines.

Utkarsh


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 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 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.
>
> Cheers,
>
> --
> ____________________________________________________________
> Sean McBride, B. Eng                 sean at rogue-research.com
> Rogue Research                        www.rogue-research.com
> Mac Software Developer              Montréal, Québec, Canada
>
>