On Tue, Nov 8, 2011 at 5:54 PM, Anne Gentle <a...@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 _______________________________________________ Mailing list: https://launchpad.net/~openstack Post to : openstack@lists.launchpad.net Unsubscribe : https://launchpad.net/~openstack More help : https://help.launchpad.net/ListHelp