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

Thierry Carrez thierry at openstack.org
Mon Jun 29 10:32:31 UTC 2015

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.

Thierry Carrez (ttx)

More information about the OpenStack-dev mailing list