openstack team mailing list archive

[Anne Gentle <anne@xxxxxxxxxxxxx>]

Thanks, Jay. I usually try to be more careful with the API names, so thanks
for clarifying.

Any other PTLs with needs or opinions here?

I think the landing page containing Draft API docs looks something like the
attached mockup, let me know your feedback.

Jay, you're the only PTL using Google Docs for feedback, others have used
the doc comments system, Disqus. I can set up doc comments feeds
specifically for RFC periods on particular specs, though your Google Docs
approach works fine also. It would be nice to standardize but I also like
that Google docs lets you click "Resolved" on a comment.

I have the ability to make DRAFT in big red letters on the output. I could
also put RFC as a watermark on the page during the RFC period in addition
to the DRAFT in each page.

I mostly want to ensure easy access so that the draft APIs get plenty of
comments and reviews.

Thanks,
Anne

*Anne Gentle*
anne@xxxxxxxxxxxxx
 my blog <http://justwriteclick.com/> | my
book<http://xmlpress.net/publications/conversation-community/>|
LinkedIn <http://www.linkedin.com/in/annegentle> |
Delicious<http://del.icio.us/annegentle>|
Twitter <http://twitter.com/annegentle>
On Wed, Nov 9, 2011 at 8:41 AM, Jay Pipes <jaypipes@xxxxxxxxx> wrote:

> On Tue, Nov 8, 2011 at 5:54 PM, Anne Gentle <anne@xxxxxxxxxxxxx> 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
>

Attachment: OpenStackDraftAPIMockup.png
Description: PNG image