[openstack-dev] Termination of the title line of commit messages

Angus Salkeld asalkeld at redhat.com
Tue Jun 25 00:14:27 UTC 2013


On 24/06/13 22:50 +0100, Mark McLoughlin wrote:
>Hey,
>
>Pulling this out of gerrit for discussion.
>
>Background is one of my patches to diskimage-builder was -1ed because I
>terminated the title line of the commit message with a period:
>
>  https://review.openstack.org/33262
>
>This is actually the exact opposite to what I consider normal practice
>for git commit messages as I explained in the review and the tripleo
>wiki page, so I proposed a hacking change here:
>
>  https://review.openstack.org/33789

Can't we just agree to not -1 on this issue? This seems like a major
waste of people resources.

-Angus

>
>The rationale for *not* having a period is:
>
>  * With the 50 char limit, space is at a premium on the first line
>
>  * The first line is often used as the Subject: in [PATCH] emails -
>    subject lines in emails generally don't end in a period
>
>  * Examples in:
>
>      https://wiki.openstack.org/wiki/GitCommitMessages#Summary_of_GIT_commit_message_structure
>
>    don't end in period
>
>    (Note - the "should not end with a period" was only added by me
>    recently)
>
>  * Another common reference on git commit messages
>
>      http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html doesn't either
>
>  * In git's own git repo, 1.43% of commit messages in the last year
>    ended in a period
>
>  * I'm not aware of any other OpenStack project which enforces this.
>    Looking at the history of various projects for the past year (and
>    excluding merge commits which don't end with a period), the use of
>    period termination runs at between 10 and 30%.
>
>Unlike other nitpicking I tend to do with commit messages, I previously
>never thought this was worth even mentioning to committers but if some
>reviewers were going to start -1ing people for the *correct* style then
>I figured it was best to clear it up.
>
>Now, for Robert's comments in the review:
>
>> It would have been nice for this to be discussed rather than dropping
>> into the communal standards without warning;
>
>I tried my best do explain why period termination is broken in the
>diskimage-builder review and wiki page, so it's not like I was trying to
>avoid a discussion.
>
>In any case, if I, jogo and sdague got this wrong somehow, the mistake
>is only a git-revert away from being corrected.
>
>> the prior documentation *did not* require a period,
>
>Yes, but the examples didn't use a period which obviously means a policy
>to *require* a period is a bit bizarre.
>
>I'm pretty confident that danpb didn't mention this when he wrote the
>page because he either felt it was obvious or not worth mentioning. I've
>cc-ed him to be sure.
>
>> and the reference that was sourced that
>> doesn't use them is one in the git-via-email world which is not how
>> OpenStack does *any* of it's git communications, so the 'gets used
>> like subject line of emails' point is entirely irrelevant.
>
>git was born came from a git-via-email world and its usage conventions
>reflect that. I raised the subject line point to try and explain how git
>conventions may have arisen.
>
>> In TripleO we have been using a period because the first line of the
>> commit message acts like the first line of a docstring: it is a pithy
>> description of the object it describes. Docstrings are also space
>> limited, and yet PEP8 happily requires good sentence structure and
>> grammar there.
>
>It's not a docstring, though. It's a git commit message.
>
>> tl;dr - this is an unpythonic change, and the lack of discussion is
>> quite annoying.
>
>Well, the former point is irrelevant and hopefully this email corrects
>the latter point :)
>
>Cheers,
>Mark.
>
>
>_______________________________________________
>OpenStack-dev mailing list
>OpenStack-dev at lists.openstack.org
>http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev



More information about the OpenStack-dev mailing list