openstack team mailing list archive

[Soren Hansen <soren@xxxxxxxxxxx>]

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.


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.

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.

Second of all, if this is done right, it could be used as a tool to
ensure that you don't accidentally make a change that breaks the
published API.

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

You seem to be assuming that people will just throw random bits and
bytes into patches and others will blindly approve these patches.

Validating API (and corresponding docs) changes is of course part of
the review process, and there are plenty of things we can do to make
this robust and reliable and automatically catch it if it changes
unexpectedly.

> Second, I don't think that the core OpenStack API should change with every
> OpenStack release.
[...]
> implementations for it. These efforts become very difficult if the spec is
> in constant flux.

Again, it's not like the API will change randomly every half hour. It
will change when the developers want it to change. There's a review
process. And mindful developers. And even if they aren't mindful, you
can freeze the documentation or maintain it separately all you want,
but if the code changes, it changes.

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