On Mon, Jun 24, 2013 at 3:19 PM, Sean Dague <s...@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@lists.openstack.**org <OpenStack-dev@lists.openstack.org> > http://lists.openstack.org/**cgi-bin/mailman/listinfo/**openstack-dev<http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev> >
_______________________________________________ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev