openstack team mailing list archive

[Vishvananda Ishaya <vishvananda@xxxxxxxxx>]

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