Open Stack

On 06/24/2013 05:56 PM, Mark McLoughlin wrote:
> On Mon, 2013-06-24 at 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
>>
>> 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 :)
> 
> I missed this point:
> 
>> Also not that space is limited to 50 characters by choice, not
>> necessity (the very same external reference about git commit messages
>> pointed out that 50 is not a hard limit). It is a hard limit for us...
>> because we chose to make it so. 
> 
> It's another pretty common git usage convention - I think the idea is to
> make output like 'git log --oneline' fit on 80 char terminals. The
> numbers don't add up, though, so maybe it's another thing from the
> git-via-email world. Also, the idea is probably to take into account
> that the first line can be quoted by e.g. 'Merge "foo"' or 'Revert
> "foo"' in the first line of other commit messages.

Long commit messages also look like poop in gerrit, and I don't think
anyone cares enough about bucking this style thing to go write Java to
fix it.

50 chars is common enough that vim syntax highlighting groks it. I see
no reason to choose a different thing.

Why 50? NO CLUE