Open Stack

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.

Cheers,
Mark.