Open Stack

On Sat, Nov 2, 2013 at 4:55 PM, Christopher Armstrong <
chris.armstrong at rackspace.com> wrote:

> On Sat, Nov 2, 2013 at 4: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
>>
>
>
> I like this idea. I'd also propose that the format of the specification be
> something machine-readable, such as API-Blueprint (a simple subset of
> markdown, apiblueprint.org, also what apiary uses, if you've ever seen
> that) or RAML (a more structured YAML-based syntax, raml.org).
> API-Blueprint is closer to what the keystone document uses.
>
> Making the documentation machine-readable means that it's much easier to
> verify that, in practice, the implementation of an API matches its
> specification and documentation, which is a problem that plagues many
> OpenStack projects right now.
>
>
Hi all,
I wouldn't expect you to know this unless you read minds, but we had a
Summit session last week and a long email thread with all the PTLs prior to
the Summit, and we decided to move all API specs into the repositories of
the project itself, and stop maintaining separate "spec" repos.

The Etherpad is here:

https://wiki.openstack.org/wiki/Summit/Icehouse/Etherpads

We are working on a document to describe how to document your API both for
future end-users and for current devs wanting to write to the specified
needs of the API. Stay tuned to all the bat channels for that.

Happy to discuss further, but after 2 years, it's time to make some
changes, and we worked hard to build consensus for the 10+ APIs we have in
OpenStack.

Thanks,
Anne


> --
> IRC: radix
> Christopher Armstrong
> Rackspace
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>


-- 
Anne Gentle
annegentle at justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20131113/4a66e226/attachment.html>