Open Stack

On Wed, Jun 24, 2015 at 11:28:59AM +0100, Nikola Đipanov wrote:
> Hey Nova,
> 
> I'll cut to the chase and keep this email short for brevity and clarity:
> 
> Specs don't work! They do nothing to facilitate good design happening,
> if anything they prevent it. The process layered on top with only a
> minority (!) of cores being able to approve them, yet they are a prereq
> of getting any work done, makes sure that the absolute minimum that
> people can get away with will be proposed. This in turn goes and
> guarantees that no good design collaboration will happen. To add insult
> to injury, Gerrit and our spec template are a horrible tool for
> discussing design. Also the spec format itself works for only a small
> subset of design problems Nova development is faced with.

I'd like to see some actual evidence to backup a sweeping statement
as "Specs dont work. They do nothing to facilitate good design happening,
if anything they prevent it."

Comparing Nova today, with Nova before specs were introduced, I think
that specs have had a massive positive impact on the amount of good
design and critique that is happening.

Before specs, the average blueprint had no more than 3 lines of text
in its description. Occassionally a blueprint would link to a wiki
page or google doc with some design information, but that was very
much the exception.

When I was reviewing features in Nova before specs came along, I spent
alot of time just trying to figure out what on earth the code was
actually attempting to address, because there was rarely any statement
of the problem being addressed, or any explanation of the design that
motivated the code.  This made life hard for reviewers trying to figure
out if the code was acceptable to merge.  It is pretty bad for contributors
trying to implement new features too, as they could spend weeks or months
writing and submitting code, only to be rejected at the end because the
(lack of any design discussions) meant they missed some aspect of the
problem which in turn meant all their work was in vain. That was a collosal
waste of everyone's time and resulted in some of the very horrible code
impl decisions we're still living with today.

> That's only a subset of problems. Some more, you ask? OK. No clear
> guidelines as to what needs a spec, that defaults to "everything does".
> And spec being the absolute worst way to judge the validity of some of
> the things that do require them.
> 
> Examples of the above are everywhere if you care to look for them but
> some that I've hit _this week_ are [1] (spec for a quick and dirty fix?!
> really?!) [2] (spec stuck waiting for a single person to comment
> something that is an implementation detail, and to make matter worse the
> spec is for a bug fix) [3] (see how ill suited the format is for a
> discussion + complaints about grammar and spelling instead of actual
> point being made).
> 
> Nova's problem is not that it's big, it's that it's big _and_ tightly
> coupled. This means no one can be trusted to navigate the mess
> successfully, so we add the process to stop them. What we should be
> doing is fixing the mess, and the very process is preventing that.
> 
> Don't take my word for it - ask the Gantt subteam who have been trying
> to figure out the scheduler interface for almost 4 cycles now. Folks
> doing Cells might have a comment on this too.
> 
> The good news is that we have a lot of stuff in place already to help us
> reduce this massive coupling of everything. We have versioned objects,
> we have versioned RPC. Our internal APIs are terrible, and provide no
> isolation, but we have the means to iterate and figure it out.
> 
> I don't expect this process issues will get solved quickly, If it were
> up to me I'd drop the whole thing, but I understand that it's not how
> it's done.
> 
> I do hope this makes people think, discuss and move things into the
> direction of facilitating quality software development instead of
> outright preventing it. I'll follow up with some ideas on how to go
> forward once a few people have commented back.

I will agree that the specs process has a number of flaws - in particular
I think we've treated it as too much of a rigid process resulting it in
being very beurocractic. In particular I think are missing an ability to
be pragmmatic in decisions about the level of design required and whether
specs are required. The idea of allowing blueprints without specs in
some cases was an attempt to address this, but I don't feel it has been
very successful - there is still too much stuff being forced through
the specs process unncessarily imho.

I've repeatedly stated that the fact that we created an even smaller
clique of people to approve specs (nova-drivers which is a tiny subset
of the already faaaar too small nova-core) is madness, as it creates
an even worse review burden on them, and thus worsens the bottleneck
than we already have.

In reviewing specs, we also often get into far too much detail about
the actual implementation, which is really counterproductive. eg when
get down to bikeshedding about the names of classes, types of object
attributes, and so forth, it is really insane. That level of detail
and bikesheeding belongs in the code review, not the design for the
most part.

Specs are also inflexible when it comes to dealing with features that
cross multiple projects, because we silo'd spec reviews against the
individual projects. This is sub-optimal, but ultimately not a show
stopper.

I also think the way we couple spec approval & reviews to the dev
cycles is counterproductive. We should be willing to accept and
review specs at any point in any cycle, and once approved they should
remain valid for a prolonged period of time - not require us to go
through re-review every new dev cycle as again that's just creating
extra burden. We should of course though reserve the right to unapprove
specs if circumstances change, invlidating the design for the previous
approval.

In short specs are far from perfect, but to say specs don't solve/help
anything todo with design in nova is really ignoring our history from
before the time specs existed. We must continue to improve our process
overall the biggest thing we lost IMHO is agility and pragmatism in
our decision making - I think we can regain that without throwing away
the specs idea entirely.

Regards,
Daniel
-- 
|: http://berrange.com      -o-    http://www.flickr.com/photos/dberrange/ :|
|: http://libvirt.org              -o-             http://virt-manager.org :|
|: http://autobuild.org       -o-         http://search.cpan.org/~danberr/ :|
|: http://entangle-photo.org       -o-       http://live.gnome.org/gtk-vnc :|