openstack team mailing list archive

[Jay Pipes <jaypipes@xxxxxxxxx>]

Hi Vish! Comments inline...

On Mon, Aug 22, 2011 at 6:43 PM, Vishvananda Ishaya
<vishvananda@xxxxxxxxx> wrote:
> Hey Everyone,
> We discussed at the Diablo design summit having API spec changes be proposed
> along with code changes and reviewed according to the merge process that we
> use for code.  This has been impossible up until now because the canonical
> spec has been in the openstack-manuals project.

Well, it's not been impossible :) It's just that the openstack-manuals
project doesn't go through the same code review process as Nova,
Swift, and Glance :) That can easily be changed, no?

> My suggestion is that we move the openstack-compute spec into the nova
> source tree.  During a six-month release we can propose changes to the spec
> by proposing along with the code that changes it.  In the final freeze for
> the release, we can increment the spec version number and copy the current
> version of the spec into openstack-manuals and that will be the locked down
> spec for that release.

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.

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...

Just my 2 cents,
-jay

> This means that openstack 1.1 will be the official spec for diablo, at which
> point we will start working on a new api (we can call it 1.2 but it might be
> best to use a temporary name like 'latest') during the essex release cycle,
> then at essex release we lock the spec down and it becomes the new version
> of the openstack api.
> Ultimately I would like the spec to be generated from the code, but as a
> first pass, we should at least be able to edit the future version of the
> spec as we make changes.  I've proposed the current version of the spec
> here:
> https://code.launchpad.net/~vishvananda/nova/add-api-docs/+merge/72506
> Are there any issues with this approach?
> Vish
> _______________________________________________
> Mailing list: https://launchpad.net/~openstack
> Post to     : openstack@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~openstack
> More help   : https://help.launchpad.net/ListHelp
>
>