+1
On Aug 22, 2011, at 5:06 PM, Jay Pipes <jaypi...@gmail.com> wrote: > ++ > > On Mon, Aug 22, 2011 at 7:59 PM, Jorge Williams > <jorge.willi...@rackspace.com> 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@lists.launchpad.net >> Unsubscribe : https://launchpad.net/~openstack >> More help : https://help.launchpad.net/ListHelp >> >> > > _______________________________________________ > Mailing list: https://launchpad.net/~openstack > Post to : openstack@lists.launchpad.net > Unsubscribe : https://launchpad.net/~openstack > More help : https://help.launchpad.net/ListHelp _______________________________________________ Mailing list: https://launchpad.net/~openstack Post to : openstack@lists.launchpad.net Unsubscribe : https://launchpad.net/~openstack More help : https://help.launchpad.net/ListHelp