Open Stack

On Mon, Jun 24, 2013 at 3:19 PM, Sean Dague <sean at dague.net> wrote:

> On 06/24/2013 06:15 PM, Monty Taylor wrote:
>
>>
>>
>> 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<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<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<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<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
>>
>
> As long as it gets auto enforced in hacking, I'll adapt to whatever. I
> admit I've been bleeding my first line to 72 characters recently as I
> wasn't sure we were still enforcing at 50. But I'm adaptable to 50. Makes
> you get to the point with that first line.


FWIW we say 50 and enforce 72 (
https://github.com/openstack-dev/hacking/blob/master/hacking/core.py#L778).


>
>
>         -Sean
>
> --
> Sean Dague
> http://dague.net
>
>
> ______________________________**_________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.**org <OpenStack-dev at lists.openstack.org>
> http://lists.openstack.org/**cgi-bin/mailman/listinfo/**openstack-dev<http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20130624/05d07162/attachment.html>