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

Kyle Mestery mestery at mestery.com
Mon Jun 29 15:27:51 UTC 2015

On Mon, Jun 29, 2015 at 4:32 AM, Thierry Carrez <thierry at openstack.org>

> 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.
This is exactly what we realized in Neutron, and why we moved to an Request
For Enhancement (RFE) process [1]. So far, it's been pretty good. A slimmed
down spec (only required if an RFE bug needs a bit more fleshing out),
design documents merging in-tree with the code, and no deadlines. I've not
heard any complaints so far and we're liking the new model a lot better.


[1] http://lists.openstack.org/pipermail/openstack-dev/2015-June/066217.html

> 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)
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20150629/ad1a75da/attachment.html>

More information about the OpenStack-dev mailing list