<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Mon, Jun 24, 2013 at 3:19 PM, Sean Dague <span dir="ltr"><<a href="mailto:sean@dague.net" target="_blank">sean@dague.net</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div class=""><div class="h5">On 06/24/2013 06:15 PM, Monty Taylor wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<br>
<br>
On 06/24/2013 05:56 PM, Mark McLoughlin wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
On Mon, 2013-06-24 at 22:50 +0100, Mark McLoughlin wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
Hey,<br>
<br>
Pulling this out of gerrit for discussion.<br>
<br>
Background is one of my patches to diskimage-builder was -1ed because I<br>
terminated the title line of the commit message with a period:<br>
<br>
<a href="https://review.openstack.org/33262" target="_blank">https://review.openstack.org/<u></u>33262</a><br>
<br>
This is actually the exact opposite to what I consider normal practice<br>
for git commit messages as I explained in the review and the tripleo<br>
wiki page, so I proposed a hacking change here:<br>
<br>
<a href="https://review.openstack.org/33789" target="_blank">https://review.openstack.org/<u></u>33789</a><br>
<br>
The rationale for *not* having a period is:<br>
<br>
* With the 50 char limit, space is at a premium on the first line<br>
<br>
* The first line is often used as the Subject: in [PATCH] emails -<br>
subject lines in emails generally don't end in a period<br>
<br>
* Examples in:<br>
<br>
<a href="https://wiki.openstack.org/wiki/GitCommitMessages#Summary_of_GIT_commit_message_structure" target="_blank">https://wiki.openstack.org/<u></u>wiki/GitCommitMessages#<u></u>Summary_of_GIT_commit_message_<u></u>structure</a><br>
<br>
don't end in period<br>
<br>
(Note - the "should not end with a period" was only added by me<br>
recently)<br>
<br>
* Another common reference on git commit messages<br>
<br>
<a href="http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html" target="_blank">http://tbaggery.com/2008/04/<u></u>19/a-note-about-git-commit-<u></u>messages.html</a> doesn't either<br>
<br>
* In git's own git repo, 1.43% of commit messages in the last year<br>
ended in a period<br>
<br>
* I'm not aware of any other OpenStack project which enforces this.<br>
Looking at the history of various projects for the past year (and<br>
excluding merge commits which don't end with a period), the use of<br>
period termination runs at between 10 and 30%.<br>
<br>
Unlike other nitpicking I tend to do with commit messages, I previously<br>
never thought this was worth even mentioning to committers but if some<br>
reviewers were going to start -1ing people for the *correct* style then<br>
I figured it was best to clear it up.<br>
<br>
Now, for Robert's comments in the review:<br>
<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
It would have been nice for this to be discussed rather than dropping<br>
into the communal standards without warning;<br>
</blockquote>
<br>
I tried my best do explain why period termination is broken in the<br>
diskimage-builder review and wiki page, so it's not like I was trying to<br>
avoid a discussion.<br>
<br>
In any case, if I, jogo and sdague got this wrong somehow, the mistake<br>
is only a git-revert away from being corrected.<br>
<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
the prior documentation *did not* require a period,<br>
</blockquote>
<br>
Yes, but the examples didn't use a period which obviously means a policy<br>
to *require* a period is a bit bizarre.<br>
<br>
I'm pretty confident that danpb didn't mention this when he wrote the<br>
page because he either felt it was obvious or not worth mentioning. I've<br>
cc-ed him to be sure.<br>
<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
and the reference that was sourced that<br>
doesn't use them is one in the git-via-email world which is not how<br>
OpenStack does *any* of it's git communications, so the 'gets used<br>
like subject line of emails' point is entirely irrelevant.<br>
</blockquote>
<br>
git was born came from a git-via-email world and its usage conventions<br>
reflect that. I raised the subject line point to try and explain how git<br>
conventions may have arisen.<br>
<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
In TripleO we have been using a period because the first line of the<br>
commit message acts like the first line of a docstring: it is a pithy<br>
description of the object it describes. Docstrings are also space<br>
limited, and yet PEP8 happily requires good sentence structure and<br>
grammar there.<br>
</blockquote>
<br>
It's not a docstring, though. It's a git commit message.<br>
<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
tl;dr - this is an unpythonic change, and the lack of discussion is<br>
quite annoying.<br>
</blockquote>
<br>
Well, the former point is irrelevant and hopefully this email corrects<br>
the latter point :)<br>
</blockquote>
<br>
I missed this point:<br>
<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
Also not that space is limited to 50 characters by choice, not<br>
necessity (the very same external reference about git commit messages<br>
pointed out that 50 is not a hard limit). It is a hard limit for us...<br>
because we chose to make it so.<br>
</blockquote>
<br>
It's another pretty common git usage convention - I think the idea is to<br>
make output like 'git log --oneline' fit on 80 char terminals. The<br>
numbers don't add up, though, so maybe it's another thing from the<br>
git-via-email world. Also, the idea is probably to take into account<br>
that the first line can be quoted by e.g. 'Merge "foo"' or 'Revert<br>
"foo"' in the first line of other commit messages.<br>
</blockquote>
<br>
Long commit messages also look like poop in gerrit, and I don't think<br>
anyone cares enough about bucking this style thing to go write Java to<br>
fix it.<br>
<br>
50 chars is common enough that vim syntax highlighting groks it. I see<br>
no reason to choose a different thing.<br>
<br>
Why 50? NO CLUE<br>
</blockquote>
<br></div></div>
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.</blockquote>
<div><br></div><div style>FWIW we say 50 and enforce 72 (<a href="https://github.com/openstack-dev/hacking/blob/master/hacking/core.py#L778">https://github.com/openstack-dev/hacking/blob/master/hacking/core.py#L778</a>).</div>
<div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><span class=""><font color="#888888"><br>
<br>
-Sean<br>
<br>
-- <br>
Sean Dague<br>
<a href="http://dague.net" target="_blank">http://dague.net</a></font></span><div class=""><div class="h5"><br>
<br>
______________________________<u></u>_________________<br>
OpenStack-dev mailing list<br>
<a href="mailto:OpenStack-dev@lists.openstack.org" target="_blank">OpenStack-dev@lists.openstack.<u></u>org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/<u></u>cgi-bin/mailman/listinfo/<u></u>openstack-dev</a><br>
</div></div></blockquote></div><br></div></div>