Open Stack

Today in the meeting we discussed the issue of how to handle issues with 
"nitpicks" to contributions.  We acknowledged the following concerns:

1)  We don't want to frustrate new (or old) contributors
2)  We want to encourage contributions
3)  We want to keep the docs "clean"
4)  We want to prevent a flood of additional bugs

To do that, we agreed on the following:

If you see something simple you can patch yourself, feel free to do 
that.  BEFORE doing that, leave a comment with some variation on the 
text here:  https://etherpad.openstack.org/p/docs-fixed-it-for-you

What we discussed, but didn't quite agree (because we didn't have time 
to discuss it properly) was what to do for changes that are too complex 
(or time consuming) for the reviewer to patch themselves.

In this situation, we need to balance contributor frustration and 
efficient use of their time with a desire to prevent the introduction of 
more new bugs than necessary.  To do that, I would propose that a 
reviewer should leave a comment explaining what needs to be fixed 
(something like this: 
https://etherpad.openstack.org/p/docs-please-fix-this), and offer the 
contributor the option to either fix it or file a new bug and paste the 
URL for that bug into a comment.

Now, before you have an allergic reaction to "file a new bug", please 
hear me out. :)

The purpose of this process is to make sure contributors know how to do 
this properly, and to keep things clean.  By doing it this way, the 
contributor will know how to do it correctly next time, and in most 
cases, filing a new bug will be more of a hassle than just fixing it 
(which is what we want).  Also, by offering them the option, we are 
using psychology to make them more willing to participate and do the 
right thing. :)

Undoubtedly there will be some reduced number of cases where the 
contributor chooses to just file a new bug.  We can use these for docs 
mentoring, and as "low-hanging-fruit", they will not remain unassigned 
for long.

OK, hopefully this is a good compromise, yes?

---  Nick