openstack team mailing list archive

[Jan Drake <jan_drake@xxxxxxxxxxx>]

+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