Open Stack

On Tue, Nov 8, 2011 at 5:54 PM, Anne Gentle <anne at openstack.org> wrote:
> Hi all -
>
> We have three projects that need to have draft API docs (for a new API
> version) published for feedback and consumption during the Essex timeframe.
> (Quantum 1.0>1.1, Glance 1.1>2.0, and Nova 1.1>2.1)

Small, but important correction: It is not the Quantum, Glance API or
the Nova API, but the OpenStack Networks API, Images API and Compute
API :)

I raised this issue at the last design summit and have continued to
raise it on the mailing list in various discussions, but I think it is
important to state that how an API evolves can and should be separated
from a reference implementation of that API.

There's a reason why the word "Glance" doesn't appear anywhere in the
proposed Images API 2.0 drafts.

> I'd like to get ideas about where those should be published and some of the
> requirements around their draft status.

So... are we talking about when/where to publish the proposed draft
spec AFTER it has gone through an RFC period and gotten feedback? Or
are we talking about codifying the way we go about getting feedback
during an RFC period on a proposed API?

I kind of like the way that commenting on Google Docs has worked for
the Images API 2.0 proposed drafts. It's easy enough to comment on a
block of the document and respond -- and emails get sent out notifying
you of new or updated comments. We got feedback from 12 individuals
via comments on the Google Doc, and through an iterative process, have
responded to those comments and/or incorporated the feedback back into
the proposal.

I'm in the process of completing the final requested changes to the
second draft document and was then planning to email the mailing list
with a "OK, here is the final draft. Last chance to comment before we
begin implementing it in Glance" post. I'd like to work with you on
taking the proposed draft Google Doc into the main
http://docs.openstack.org/api/ site.

The current 1.x API is here:

http://docs.openstack.org/api/openstack-image-service/1.0/content/

I'd love it if we could put the final 2.0 proposal here:

http://docs.openstack.org/api/openstack-image-service/2.0/content/

With a link to it from the main API area, noting that the 2.0 API is
in DRAFT mode until X date -- to be determined later?

> Is there a need for special treatment for "RFC" vs. "Draft" designations
> such as RFC for a certain time period, then Draft?

I think the RFC period should run by the respective PTL for the
project and then a DRAFT mode indicates it is in the period AFTER the
RFC time and before the proposed API is fully implemented by a
project. That work for you?

> Do these need drafts need to be published to docs.openstack.org/api, or is
> that site for "final" APIs for end-users?

See above. I think having the DRAFT on the API site would be very
helpful (again, after the RFC period closes)

> I envision introducing more
> confusion than is already present if we publish them side-by-side.
> Do these API drafts need their own site for the RFC/Draft period, such as
> api.openstack.org/drafts?

No, I think just clearly marking the draft API with DRAFT in big red
letters is good :)

Cheers, and thanks for caring about this subject that's close to my heart!
-jay