openstack team mailing list archive

[Jay Pipes <jaypipes@xxxxxxxxx>]

No problems with anything you say below...

-jay

On Mon, Aug 22, 2011 at 9:59 PM, Vishvananda Ishaya
<vishvananda@xxxxxxxxx> 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.
>>
>> 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
>