[openstack-dev] [Solum] Create a source repo for the API specification?

Adrian Otto adrian.otto at rackspace.com
Sat Nov 2 21:54:54 UTC 2013


Jay,

On Nov 2, 2013, at 2:39 PM, Jay Pipes <jaypipes at gmail.com> wrote:

> Hi all,
> 
> One of the most important aspects in the early stages of Solum development will be the consensus building and stabilization of the Solum API specification. A solid API spec aid in the speeding up the pace of innovation in the Solum contributor community.
> 
> One of the aspects of the Keystone development process that I think is a big benefit is the separate source repository that stores the OpenStack Identity API specifications:
> 
> https://github.com/openstack/identity-api
> 
> When new versions of the API specification are debated or new extensions are proposed, patches are made to the specification markdown documents and reviewed in the exact same manner that regular code is on the https://review.openstack.org Gerrit site. Contributors are free to annotate the proposed changes to the API specification in the same way that they would make inline code comments on a regular code review. Here's an example for a proposed change that I recently made:
> 
> https://review.openstack.org/#/c/54215/10
> 
> I'd like to propose that Solum do the same: have a separate source repository for the API specification.
> 
> Thoughts?
> -jay

This strikes me as a way to make the API design process more collaborative, particularly in the way that it allows us to get a picture of perspectives from a wide range of contributors, and the ability to to make line-level comments like we do with source code. I think that will be much more powerful than what we have today with the wiki page. Thanks for suggesting it Jay!

Adrian


More information about the OpenStack-dev mailing list