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

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

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.

        -Sean

--
Sean Dague
http://dague.net

_______________________________________________
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Reply via email to