Let me start by saying that I have no idea why we're having this discussion again. We talked about it at the design summit and we agreed we'd move forward in pretty much exactly the way Vish describes it.
2011/8/23 Jorge Williams <jorge.willi...@rackspace.com>: > 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. I think you're making unsound assumptions about the implementation of the "API docs live in code" concept. First of all, this is primarily about consolidating the maintenance of the code and the API into one place. Having API docs that are ahead of the code is pointless. It's describing an API that doesn't exist. Having it lag behind the code also helps noone. To address this, we keep the docs in the code repository. When I write a patch that alters the API in some way, the corresponding doc change should accompany it. Whether it's written by hand or autogenerated based on introspection is beside the point. The point is to be able to look at any point in version control and see what API I can expect to work with that code. This is completely orthogonal to when the discussion about the API happens. It can happen as early as you like, you can (informally) publish the expected API as early as you want. "Expected" is the keyword. When you sit down and start implementing something, sometimes you just realise that the API you were expecting to implement is really, really awkward to do, but a slightly different API for the same functionality would be simple and elegant. In those cases, I see no particular reason to stick to the originally published, expected API. Of course we need a deadline (probably around feature freeze) at which point no more changes can be made to the exposed API's so we don't rip the rug out from under everyone every day up until release. Second of all, if this is done right, it could be used as a tool to ensure that you don't accidentally make a change that breaks the published API. > 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). You seem to be assuming that people will just throw random bits and bytes into patches and others will blindly approve these patches. Validating API (and corresponding docs) changes is of course part of the review process, and there are plenty of things we can do to make this robust and reliable and automatically catch it if it changes unexpectedly. > Second, I don't think that the core OpenStack API should change with every > OpenStack release. [...] > implementations for it. These efforts become very difficult if the spec is > in constant flux. Again, it's not like the API will change randomly every half hour. It will change when the developers want it to change. There's a review process. And mindful developers. And even if they aren't mindful, you can freeze the documentation or maintain it separately all you want, but if the code changes, it changes. -- Soren Hansen | http://linux2go.dk/ Ubuntu Developer | http://www.ubuntu.com/ OpenStack Developer | http://www.openstack.org/ _______________________________________________ Mailing list: https://launchpad.net/~openstack Post to : openstack@lists.launchpad.net Unsubscribe : https://launchpad.net/~openstack More help : https://help.launchpad.net/ListHelp
