openstack team mailing list archive

[Jay Pipes <jaypipes@xxxxxxxxx>]

++

On Mon, Aug 22, 2011 at 7:59 PM, Jorge Williams
<jorge.williams@xxxxxxxxxxxxx> 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.
>
> 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.
> -jOrGe W.
> On Aug 22, 2011, at 5:43 PM, Vishvananda Ishaya wrote:
>
> Hey Everyone,
> We discussed at the Diablo design summit having API spec changes be proposed
> along with code changes and reviewed according to the merge process that we
> use for code.  This has been impossible up until now because the canonical
> spec has been in the openstack-manuals project.
> My suggestion is that we move the openstack-compute spec into the nova
> source tree.  During a six-month release we can propose changes to the spec
> by proposing along with the code that changes it.  In the final freeze for
> the release, we can increment the spec version number and copy the current
> version of the spec into openstack-manuals and that will be the locked down
> spec for that release.
> This means that openstack 1.1 will be the official spec for diablo, at which
> point we will start working on a new api (we can call it 1.2 but it might be
> best to use a temporary name like 'latest') during the essex release cycle,
> then at essex release we lock the spec down and it becomes the new version
> of the openstack api.
> Ultimately I would like the spec to be generated from the code, but as a
> first pass, we should at least be able to edit the future version of the
> spec as we make changes.  I've proposed the current version of the spec
> here:
> https://code.launchpad.net/~vishvananda/nova/add-api-docs/+merge/72506
> Are there any issues with this approach?
> Vish
>
> This email may include confidential information. If you received it in
> error, please delete it.
> _______________________________________________
> Mailing list: https://launchpad.net/~openstack
> Post to     : openstack@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~openstack
> More help   : https://help.launchpad.net/ListHelp
>
>