On Tue, 2014-06-24 at 13:56 -0700, Clint Byrum wrote: > Excerpts from Mark McLoughlin's message of 2014-06-24 12:49:52 -0700: > > On Tue, 2014-06-24 at 09:51 -0700, Clint Byrum wrote: > > > Excerpts from Monty Taylor's message of 2014-06-24 06:48:06 -0700: > > > > On 06/22/2014 02:49 PM, Duncan Thomas wrote: > > > > > On 22 June 2014 14:41, Amrith Kumar <amr...@tesora.com> wrote: > > > > >> In addition to making changes to the hacking rules, why don't we > > > > >> mandate also > > > > >> that perceived problems in the commit message shall not be an > > > > >> acceptable > > > > >> reason to -1 a change. > > > > > > > > > > -1. > > > > > > > > > > There are some /really/ bad commit messages out there, and some of us > > > > > try to use the commit messages to usefully sort through the changes > > > > > (i.e. I often -1 in cinder a change only affects one driver and that > > > > > isn't clear from the summary). > > > > > > > > > > If the perceived problem is grammatical, I'm a bit more on board with > > > > > it not a reason to rev a patch, but core reviewers can +2/A over the > > > > > top of a -1 anyway... > > > > > > > > 100% agree. Spelling and grammar are rude to review on - especially > > > > since we have (and want) a LOT of non-native English speakers. It's not > > > > our job to teach people better grammar. Heck - we have people from > > > > different English backgrounds with differing disagreements on what good > > > > grammar _IS_ > > > > > > > > > > We shouldn't quibble over _anything_ grammatical in a commit message. If > > > there is a disagreement about it, the comments should be ignored. There > > > are definitely a few grammar rules that are loose and those should be > > > largely ignored. > > > > > > However, we should correct grammar when there is a clear solution, as > > > those same people who do not speak English as their first language are > > > likely to be confused by poor grammar. > > > > > > We're not doing it to teach grammar. We're doing it to ensure readability. > > > > The importance of clear English varies with context, but commit messages > > are a place where we should try hard to just let it go, particularly > > with those who do not speak English as their first language. > > > > Commit messages stick around forever and it's important that they are > > useful, but they will be read by a small number of people who are going > > to be in a position to spend a small amount of time getting over > > whatever dissonance is caused by a typo or imperfect grammar. > > > > The times that one is reading git messages are often the most stressful > such as when a regression has occurred in production. > > Given that, I believe it is entirely worth it to me that the commit > messages on my patches are accurate and understandable. I embrace all > feedback which leads to them being more clear. I will of course stand > back from grammar correcting and not block patches if there are many > who disagree. > > > I think specs are pretty similar and don't warrant much additional > > grammar nitpicking. Sure, they're longer pieces of text and slightly > > more people will rely on them for information, but they're not intended > > to be complete documentation. > > > > Disagree. I will only state this one more time as I think everyone knows > how I feel: if we are going to grow beyond the english-as-a-first-language > world we simply cannot assume that those reading specs will be native > speakers. Good spelling and grammar helps us grow. Bad spelling and > grammar holds us back.
There's two sides to this coin - concern about alienating non-english-as-a-first-language speakers who feel undervalued because their language is nitpicked to death and concern about alienating english-as-a-first-language speakers who struggle to understand unclear or incorrect language. Obviously there's a balance to be struck there and different people will judge that differently, but I'm personally far more concerned about the former rather than the latter case. I expect many beyond the english-as-a-first-language world are pretty used to dealing with imperfect language but aren't so delighted with being constantly reminded that their use language is imperfect. > > Where grammar is so poor that readers would be easily misled in > > important ways, then sure that should be fixed. But there comes a point > > when we're no longer working to avoid confusion and instead just being > > pendants. Taking issue[1] with this: > > > > "whatever scaling mechanism Heat and we end up going with." > > > > because it has a "dangling preposition" is an example of going way > > beyond the point of productive pedantry IMHO :-) > > I actually agree that it would not at all be a reason to block a patch. > However, there is some ambiguity in that sentence that may not be clear > to a native speaker. It is not 100% clear if we are going with Heat, > or with the scaling mechanism. That is the only reason for the dangling > preposition debate. I'd wager you'd seriously struggle to find anyone who would interpret that sentence as "we are going with Heat", even if they were non-english-as-a-first-language speakers who had never heard of OpenStack or Heat or scaling mechanisms. You'll find plenty who would stumble over the sentence and need to re-read it, but we making design spec reading a completely frictionless experience is hardly a priority. > However, there is a debate, and thus I would _never_ > block a patch based on this rule. It was feedback.. just as sometimes > there is feedback in commit messages that isn't taken and doesn't lead > to a -1. Absolutely, and I try and be clear about that with e.g. "not a -1" or "if you're rebasing anyway, perhaps fix this". Maybe a convention for such comments would be a good thing? We often do 'nitpick' or 'femtonit', but they are often still things people are -1ing on. Mark. _______________________________________________ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev