[openstack-dev] [Nova] The unbearable lightness of specs

Nikola Đipanov ndipanov at redhat.com
Mon Jun 29 12:36:36 UTC 2015

On 06/29/2015 11:32 AM, Thierry Carrez wrote:
> Nikola Đipanov wrote:
>> It's not only about education - I think Gerrit is the wrong medium to
>> have a design discussion and do design work. Maybe you disagree as you
>> seem to imply that it worked well in some cases?
>> I've recently seen on more than a few cases how a spec "review" can
>> easily spiral into a collection of random comments that are hard to put
>> together in a coherent discussion that you could call design work.
>> If you throw in the expectation of approval into the mix, I think it
>> basically causes the opposite of good design collaboration to happen.
> On Gerrit not being the right tool for specs...
> Using code review tools to iterate on specs creates two issues:
> * Minor comments
> Line-by-line code review tools are excellent for reviewing the
> correctness of lines of code. When switching to specs, you retain some
> of that "review correctness of all lines" mindset and tend to spot
> mistakes in the details more than mistakes in the general idea. That, in
> turn, results in -1 votes that don't really mean the same thing.
> * Extra process
> Code review tools are designed to produce final versions of documents.
> For specs we use a template to enforce a minimal amount of details, but
> those are already too much for most small features. To solve that issue,
> we end up having to binary-decide when something is significant enough
> to warrant a full spec. As with any line in the sand, the process end up
> being too much for things that are just beyond the line, and too little
> for things that are just before.
> IMHO the ideal tool would allow you to start with a very basic
> description of what feature you want to push. Then a discussion can
> start, and the "spec" can be refined to answer new questions or detail
> the already-sketched-out answers. Simple features can be approved really
> quickly using a one-sentence spec, while more complex features will
> develop into a full-fledged detailed document before they get approved.
> One size definitely doesn't fit all. And the discussion-based review
> (opposed to line-by-line review) discourages nitpicking on style.
> You *can* do this with Gerrit: discourage detail review + encourage idea
> review, and start small and develop the document in future patchsets
> as-needed. It's just not really encouraging that behavior for the job,
> and the overhead for simple features still means we can't track smallish
> features with it. As we introduce new tools we might switch the "feature
> approval" process to something else. In the mean time, my suggestion
> would be to use smaller templates, start small and go into details only
> if needed, and discourage nitpicking -1s.

I fully agree with the above FWIW.

This is *exactly* what I hinted at in the summary email, when I
suggested a "BP repository", with a problem statement patch that could
then potentially evolve into a full blown spec if needed.

I feel that Gerrit is bad at keeping an easily review-able history of a
discussion even for code reviews, and this problem is worse for written
text (as you point out), so looking at other tools might be useful at
some point.


More information about the OpenStack-dev mailing list