openstack team mailing list archive

[Jorge Williams <jorge.williams@xxxxxxxxxxxxx>]

Inline:

On Aug 23, 2011, at 4:40 PM, Soren Hansen wrote:

> Let me start by saying that I have no idea why we're having this
> discussion again. We talked about it at the design summit and we
> agreed we'd move forward in pretty much exactly the way Vish describes
> it.
> 

I believe I attended all discussions on the compute API.   We agreed to design the spec in a more open and agile manner -- I'm all for that.  I don't remember ever discussing generating the spec from code. I also don't remember ever discussing where the spec will live.  Not that I really care where it lives, I just don't remember talking about it.

> 
> 2011/8/23 Jorge Williams <jorge.williams@xxxxxxxxxxxxx>:
>> 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.
> 
> I think you're making unsound assumptions about the implementation of
> the "API docs live in code" concept.
> 
> First of all, this is primarily about consolidating the maintenance of
> the code and the API into one place. Having API docs that are ahead of
> the code is pointless. It's describing an API that doesn't exist.
> Having it lag behind the code also helps noone. To address this, we
> keep the docs in the code repository. When I write a patch that alters
> the API in some way, the corresponding doc change should accompany it.
> Whether it's written by hand or autogenerated based on introspection
> is beside the point. The point is to be able to look at any point in
> version control and see what API I can expect to work with that code.

Having the spec ahead of time is not pointless.  That's like saying that blueprints are pointless.  It allows us to talk about features before they make it in the code and gives us a path forward. For example, we had heated debates about the JSON format while drafting the spec. We changed the examples here and there until we found an approach that we could all live with.  Imagine if all of those changes had to be followed by a patch that change the representation 3..4..5 times, that would have been a big waste of coding effort.   Also, the spec allows us to talk about the API as a whole rather than to have to wait for the implementation to catch up to every proposed feature.  Looking at the API as a whole is important when we talk about consistency, correctness etc.  Having a spec separate from the Impl is also important when you have multiple groups writing an implementation to the spec..that's happening today with at least compute and keystone, and it's something which I think we should continue to encourage. Multiple groups can both simultaneously strive for compatible implementations, and the spc gives them a place where they can come to an agreement.  I don't see how we can make this possible if a particular implementation's code dictates what the spec is. 


> 
> This is completely orthogonal to when the discussion about the API
> happens. It can happen as early as you like, you can (informally)
> publish the expected API as early as you want. "Expected" is the
> keyword. When you sit down and start implementing something, sometimes
> you just realise that the API you were expecting to implement is
> really, really awkward to do, but a slightly different API for the
> same functionality would be simple and elegant. In those cases, I see
> no particular reason to stick to the originally published, expected
> API. Of course we need a deadline (probably around feature freeze) at
> which point no more changes can be made to the exposed API's so we
> don't rip the rug out from under everyone every day up until release.
> 

I totally agree that implementation should inform the spec. And that we should take an iterative process towards the development of the spec. The spec isn't set in stone until it's out of BETA and how much changes and the type of changes that come in depend on how stable the spec is.  The compute spec has gone through a lot of changes since it was introduced in Jan/Feb,  and it's still undergoing minor fixes at some point the *core* spec should freeze.  How and when that happens shouldn't depend on your software release cycle.  Ideally you want a *core* spec that doesn't change very often at all that gives clients a stable platform on which to develop.

I think that the underlying problem is this:  We have good documentation on where we want to go with the spec, and the devs are working really hard to get there. They might get there by the next release, but they might not. The problem is we don't have good documentation on where we are now -- at this point in time.  The fact that we have arbitrary release cycles at constant intervals means that we are forced to release something that isn't 100% compliant.  We need to document where the differences lie between the spec and the impl.  If you want to generate a report that lists those differences..I'm all for it.  But the spec itself should not be directly coupled with the code for precisely the reasons I've stated before...and we should be moving to advance both the spec (or future versions of it) and the impl so that they are aligned.

-jOrGe W.







This email may include confidential information. If you received it in error, please delete it.