openstack team mailing list archive

["Mellquist, Peter" <peter.mellquist@xxxxxx>]

I understand the benefits of being able to generate docs and specs from code since it ensures that these are in synch and that the specs follow what the code supports but ... in regard to API design this approach leaves something to be desired. There is much value in designing the APIs up front to ensure consistency, a cohesive presentation model and to ensure that API best practices are followed. APIs need to be designed and this requires an up front definition and review. I think that there is a balance here to allow enough API design up front and then an agile development process to validate and improve the APIs with real implementation. 

Peter.

-----Original Message-----
From: openstack-bounces+peter.mellquist=hp.com@xxxxxxxxxxxxxxxxxxx [mailto:openstack-bounces+peter.mellquist=hp.com@xxxxxxxxxxxxxxxxxxx] On Behalf Of Soren Hansen
Sent: Wednesday, August 24, 2011 10:03 AM
To: Jorge Williams
Cc: <openstack@xxxxxxxxxxxxxxxxxxx>
Subject: Re: [Openstack] API Spec

2011/8/24 Jorge Williams <jorge.williams@xxxxxxxxxxxxx>:
>> 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.

Generating the spec from code (or docstrings living in code, rather) was
informally discussed in San Antonio in November.

> 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.

This was the subject for an entire session in Santa Clara. Making code
and docuemtation live together to ensure they'd be in sync at all times.

>> 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.

I know it's going to be an annoying discussion when I have to quote
myself. Nevertheless:

>> 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.

Please let me know if (and how) I should elaborate on this.

> 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.

Noone is suggesting writing roughly the same code 3, 4 or 5 times. Part
of the discussion about a feature is discussing the API. We've
historically not been very good at discussing blueprints in very much
detail, but that's different issue.

> Also, the spec allows us to talk about the API as a whole

In what way are we unable to talk about the API as a whole when we're
having these discussions?

> Looking at the API as a whole is important when we talk about
> consistency, correctness etc.

Of course it is. And when we discuss the API for a feature, we have to
consider it in the context of the rest of the API.

> Having a spec separate from the Impl is also important when you have
> multiple groups writing an implementation to the spec..

It's the same people defining the API. Whether they write it by hand or
have parts of it be generated based on introspection, the output will be
the *exact* same. Who cares?

> that's happening today with at least compute and keystone, and it's
> something which I think we should continue to encourage.

OpenStack was created to stop every company wanting to do offer cloud
computing from reinventing everything and have everyone work together.
What's the use of competing implementations? We'll be right back to square one.

> Multiple groups can both simultaneously strive for compatible
> implementations, and the spc gives them a place where they can come to
> an agreement.

Yes? Can you explain how any of this is impeded by this proposal? I'm
not seeing it at all.

> I don't see how we can make this possible if a particular
> implementation's code dictates what the spec is.

I don't see the connection at all.

>> 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.

How will that happen if you want to define, bless, and publish the API
before any code is written?

> 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.

I just don't see the spec as a separate thing. It's a description of how
you expect to interact with something, but until this something exists,
what's its purpose?

> 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.

You can write specs all day long that speak about fantastic and elegant
features, but if there's no implementation, what's the use?

> 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.

Err.. No. First of all, having the spec completely decoupled of the
implementation means you have *two* arbitrary release cycles. Second of
all, if we maintain them together, we can never ever release something
that isn't complaint with the spec, because the spec will only include
what's actually implemented.

> We need to document where the differences lie between the spec and the
> impl.

No. We need to make sure there is no difference. Like, say,  having the
spec be generated from docstrings in the code and at the same time run
tests based on the contents of the docstrings to ensure that what the
docstrings says the API will accept and return is also what it actually
accepts.

-- 
Soren Hansen        | http://linux2go.dk/
Ubuntu Developer    | http://www.ubuntu.com/
OpenStack Developer | http://www.openstack.org/

_______________________________________________
Mailing list: https://launchpad.net/~openstack
Post to     : openstack@xxxxxxxxxxxxxxxxxxx
Unsubscribe : https://launchpad.net/~openstack
More help   : https://help.launchpad.net/ListHelp