Open Stack

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.