Re: [openstack-dev] Termination of the title line of commit messages
On Mon, Jun 24, 2013 at 10:50:18PM +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%. 100% agreed with all this. Using a period at the end of line is completely pointless. In absence of any explicit hacking rules to the contrary, commit messages first line should be treated in the same way as email subject line. No one ever uses a period in the email subject line. 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. Yep, I never even considered that anyone would ever want to use a period at the end of a commit message first line, so never thought to explicit tell anyone not to. Daniel -- |: http://berrange.com -o-http://www.flickr.com/photos/dberrange/ :| |: http://libvirt.org -o- http://virt-manager.org :| |: http://autobuild.org -o- http://search.cpan.org/~danberr/ :| |: http://entangle-photo.org -o- http://live.gnome.org/gtk-vnc :| ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] Termination of the title line of commit messages
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. ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] Termination of the title line of commit messages
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 ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] Termination of the title line of commit messages
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
Re: [openstack-dev] Termination of the title line of commit messages
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/**33262https://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/**33789https://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_**structurehttps://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.htmlhttp://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.htmldoesn'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
Re: [openstack-dev] Termination of the title line of commit messages
On 06/24/2013 06:19 PM, Sean Dague 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 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. I actually had a gerrit patch a while ago that would allow you to set a project to reject uploads with too-long subject lines.
Re: [openstack-dev] Termination of the title line of commit messages
On Jun 24, 2013, at 2:50 PM, Mark McLoughlin wrote: 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. I too have never thought it worth mentioning, similar to capitalizing the first word of the first line of the commit message or not. I thought any way works, as long as the first line is brief so it shows up nicely browsing on github. Personally, I treat the first line like you mention the subject line of an email, which I never capitalize or use a period at the end. Melanie ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] Termination of the title line of commit messages
On Mon, Jun 24, 2013 at 5:36 PM, Christopher Yeoh cbky...@gmail.com wrote: On Tue, Jun 25, 2013 at 7:56 AM, Joe Gordon joe.gord...@gmail.com wrote: 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 ). I'd prefer 72 than 50. I thought it was enforced at 50 and so there's been few changes I've submitted recently where I've resorted to dropping vowels to make it fit. My preference also would be there to be no period at the end Chris ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev Shorter the better IMO, I'd prefer we leave it alone but I've got enough to work on that I'll just go with the flow if everyone decides to change it. I'd prefer to have more concise summaries when browsing changes. ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] Termination of the title line of commit messages
On 25 June 2013 15:34, Joe Gordon joe.gord...@gmail.com wrote: This is exactly why we want a consensus, so we can automatically enforce it without using any human resources (at least during the review process). If we say we don't care, someone will come along and care. If we enforce one option, if someone disagrees the gate will tell them they are wrong. Not caring is a valid consensus; if the wiki page had said we explicitly don't care, I would have raised enforcing proper sentence structure in the first line here. -Rob -- Robert Collins rbtcoll...@hp.com Distinguished Technologist HP Cloud Services ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
