++ 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