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

Adam Young ayoung at redhat.com
Wed Jun 24 20:00:11 UTC 2015

On 06/24/2015 12:25 PM, Daniel P. Berrange wrote:
> Which happened repeatedly. You could say that
> the first patch submitted to the code repository should simply be a doc
> file addition, that describes the feature proposal and we should discuss
> that before then submitting code patches, but then that's essentially
> just the specs again, but with the spec doc in the main nova.git instead
> of nova-specs.git.

Something like this, yes.   I do not like the fact that the spec and the 
code are likely to be out of sync, and that the target audience for the 
spec after the feature is implemented is vanishingly small. We should 
put the effort into docs that is currently going in to specs.

But, I stand by what I said before: Gerrit is not the right tool for 
design, and specs are correspondingly owned by one person.  I think it 
is the approval part that really bugs me; the pedantry is its defining 
feature.  These are details much better hashed out in the code itself.

Specs prevent code from being written.  If you think too much code is 
written, then, yes, you will like specs. If, on the other hand, you 
think that things should be implemented and tested before being posted 
to the central repo, then specs are not nearly as valuable as end user 
docs.  I think and design in Code, not in specs.  There are too many 
details that you don't discover until you actually write the code, and 
thus the specs often do not reflect the reality of the implementation 

So, what needs to be approved is not the spec, but the problem 
statement.  Saying "don't work on this until we agree your problem is 
something to solve" is far more useful than "don't work on this until we 
approve your design."

More information about the OpenStack-dev mailing list