Open Stack

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 :)

Cheers,
Mark.