Open Stack

Inline
On Aug 22, 2011, at 4:59 PM, Jorge Williams wrote:

> Hi Vish,
> 
> I don't have a problem moving the spec out of docs manuals and into another project even the nova repo.   But, I do have a number of issues with the approach that you're proposing. First, I think that fundamentally there should be a decoupling of the spec and the implementation.   If you have the spec generated from the code than essentially the spec is whatever the code does. It's very difficult to interoperate with specs that are generated this way as the specs tend to be very brittle and opaque (since you have to study the code). If you introduce a  bug in the code that bug filters it's way all the way to the spec (this was a big problem with SOAP and CORBA). It's difficult to detect errors because you cant validate. By keeping the implementation and the spec separate you can validate one against the other. 

The spec SHOULD BE exactly what the code does, verifiably.  I'm proposing that we have exactly the existing document, only that the xml and json examples in the spec are actually generated from the code so that we know they are accurate.  This is a minor point to me though, and could be accomplished by testing the spec against the code as well.

> 
> Second, I don't think that the core OpenStack API should change with every OpenStack release. There are a number of efforts to provide multiple implementation of an existing OpenStack API.  We should encourage this, but it becomes difficult if the core spec is in constant flux.  Certainly you can use the extension mechanism to bring functionality out to market quickly, but the process of deciding what goes into the core should be more deliberate. Really good specs, shouldn't need to change very often, think HTTP, X11, SMTP, etc. We need to encourage clients to write support for our spec and we need to also encourage other implementors to write implementations for it. These efforts become very difficult if the spec is in constant flux.

Incrementing the version number is only a problem if we fail to support the old versions.  At the rate we are adding new functionality, I think we will easily need a new spec every six months for the foreseeable future.  If there are no reasonable changes in a six month period, we can skip a release and not have a new version of the spec

> 
> -jOrGe W.