[openstack-dev] [qa] Policy on spelling and grammar

Clint Byrum clint at fewbar.com
Tue Nov 12 04:12:34 UTC 2013

Excerpts from Sean Dague's message of 2013-11-11 14:19:41 -0800:
> On 11/11/2013 02:28 PM, Tim Bell wrote:
> > 
> > As a speaker of the Queen's English, I find flavor to be incorrect. Does that mean I can -1 any patch that does not use flavour ?
> > 
> > At CERN, we are working with 130 countries in a single community. The value of the contribution of non-english speakers far exceeds the occasional misunderstandings.
> > 
> > Giving grammar/spellings -1 excludes major sections of the community from contribution.
> > 
> > As our aim is meritocracy (in python, computer architecture and design rather than spelling), I'd propose
> > 
> > - If someone identifies a need for clarification/correction as part of a review, they also submit the replacement text rather than just -1.
> > - The submitter incorporates that change into a patch
> Agreed. If anyone -1s a patch for English, it better have a complete
> word for word set of replacement text as part of that review.
> Also, grammar eventually becomes the eye of the beholder, and personal
> preference, and regional difference, and style, and.... there are a lot
> of variables here. The heated debate over whether or not a period ends a
> commit subject shows how gray that is (I honestly only hold firm to
> keeping that no-period rule in hacking so people would stop -1ing over
> it, because there were actually opposing -1 wars over adding / removing
> that period).

The period argument is over and I think it exposed that we rely on the
automation for teaching as much as we do for gating.

If there are opposing positions on grammar I think that is no different
than whether to use a list comprehension or not. Other reviewers should
weigh in and the votes should dictate what passes through review.
Disagreement is o-k, and I don't think it is a bad idea to disagree even
on grammar, as ultimately it will make more information available to other
submitters and reviewers which should help homogenize the development
community around the path of least resistance.

> So unless it's actually getting in the way of the contribution being
> understood in the future, I'd much rather people leave '0' scored
> comments with the grammar / spelling micro-nits.

I assert that it gets in the way of contributions being understood in
the future. Even for a native speaker, a spelling mistake can interrupt
cognitive flow, and grammar problems often lead to ambiguity that is not
obvious until context changes in other parts of the text.

> There is a real reason for that, many of us with a lot of reviews
> completely purge anything with a -1. If you score things with a '0'
> review, core reviewers will still look at the code. But I'd hate to have
> this giant gauntlet of grammar before the code is getting looked at by
> +2ers. That seems a pretty high discouragement to new non native English
> speakers.

This is a separate issue which I believe we need to change in our
culture. We are letting the preference of any single gerrit user dictate
who will see a review.

If there are too many reviews to also be able to click through
and investigate -1's, this still just tells me that we are short on
reviewers. I revisit the -1's in all the projects I watch. It is one way
that I "review the reviewers". A few times I have reversed some minority
-1 positions with my +2, and then I notice it gets attention immediately
from other reviewers and gets approved. It should not be invisible,
it should just be another review.

More information about the OpenStack-dev mailing list