Inline On Aug 22, 2011, at 4:15 PM, Jay Pipes wrote:
> It may be just me, but having DocBookXML in the source tree is hideous > to me. Not only does it clutter the source tree with non-RST > documentation, but as you know, reviewing diffs of XML is just about > makes people want to slit their throats with a spoon. There is a > special type of person (Anne!) that seem to be impervious to the > throat-slitting urge and can successfully digest such a review > request, but for many, the process is too painful. I hate xml changes as well, but anne + people in manuals don't really have the expertise to know if something belongs in the api. *-core should be responsible for the spec for the project. > > In addition to the above gripe, the development, stability, and > enhancement of the OpenStack APIs can and should (IMHO) be managed > separately from the source code of the project. The API can evolve in > the openstack-manuals project and developers can code the OpenStack > subproject to match the API documented in openstack-manuals project > (at the tagged version). So, for instance, if the compute API needs to > change, the API documentation changes would be proposed in > openstack-manuals, reviewed, discussed and approved. The new API docs > would be published to something like > http://docs.openstack.org/compute/2.0/ and developers coding Essex > features having to do with implementing such a 2.0 API would refer to > the API documentation there while writing the feature... If we want to separate the xml code out, we can do a separate nova-spec repo for the spec, but this should be managed by nova-core > > Just my 2 cents, > -jay _______________________________________________ Mailing list: https://launchpad.net/~openstack Post to : openstack@lists.launchpad.net Unsubscribe : https://launchpad.net/~openstack More help : https://help.launchpad.net/ListHelp