← Back to team overview

openstack team mailing list archive

Re: API Spec

 

I say we up the version number when we can't ensure backward compatibility.  As to how long older versions should be supported.  Hard to say.  It depends on a lot of factors, and at the end of the day it may come up to how popular a version is and how  willing and able operators and client devs are to upgrading.

-jOrGe W.


On Aug 22, 2011, at 8:49 PM, Thor Wolpert wrote:

> I agree the Specs shouldn't change often ... but just to use your
> examples, they where all simplifications of larger specs that took
> years to create.
> 
> If an API changes and is deprecated, how long does backwards
> compatibility stay in place?
> 
> Thanks,
> Thor W
> 
> On Mon, Aug 22, 2011 at 5:49 PM, Jan Drake <jan_drake@xxxxxxxxxxx> wrote:
>> +1
>> 
>> 
>> 
>> 
>> On Aug 22, 2011, at 5:06 PM, Jay Pipes <jaypipes@xxxxxxxxx> wrote:
>> 
>>> ++
>>> 
>>> 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
>>>> 
>>>> 
>>> 
>>> _______________________________________________
>>> Mailing list: https://launchpad.net/~openstack
>>> Post to     : openstack@xxxxxxxxxxxxxxxxxxx
>>> Unsubscribe : https://launchpad.net/~openstack
>>> More help   : https://help.launchpad.net/ListHelp
>> 
>> _______________________________________________
>> Mailing list: https://launchpad.net/~openstack
>> Post to     : openstack@xxxxxxxxxxxxxxxxxxx
>> Unsubscribe : https://launchpad.net/~openstack
>> More help   : https://help.launchpad.net/ListHelp
>> 
> 
> _______________________________________________
> Mailing list: https://launchpad.net/~openstack
> Post to     : openstack@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~openstack
> More help   : https://help.launchpad.net/ListHelp

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



Follow ups

References