On Aug 22, 2011, at 8:59 PM, Vishvananda Ishaya wrote: > 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.
Agreed there should be someone in the loop that can help validate the changes. A manuals person alone should not suffice to let those type of changes go into the spec. I think we can adjust our process to be able to accomplish this. Doesn't gerrit help for this sort of stuff? >> >> 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 Having a separate nova-spec repo is a good idea. I've never been a fan of having them all in a single repo. You still want a writer in the loop to check style, apply the latest templates, do general editing etc. -jOrGe W. 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
