Open Stack

On 10/10/2014 02:05 AM, Christopher Yeoh wrote:
> I agree with what you've written on the wiki page. I think our priority
> needs to be to flesh out
> https://wiki.openstack.org/wiki/Governance/Proposed/APIGuidelines
> so we have something to reference when reviewing specs. At the moment I
> see that document as something anyone should be able to document a
> project's API convention even if they conflict with another project for
> the moment. Once we've got a fair amount of content we can start as a
> group resolving
> any conflicts.

Agreed that we should be fleshing out the above wiki page. How would you 
like us to do that? Should we have an etherpad to discuss individual 
topics? Having multiple people editing the wiki page offering commentary 
seems a bit chaotic, and I think we would do well to have the Gerrit 
review process in place to handle proposed guidelines and rules for 
APIs. See below for specifics on this...

>     Speaking of the wiki page, I wrote it very matter-of-factly. As if
>     this is the way things are. They’re not. The wiki page is just a
>     starting point. If something was missed, add it. If something can be
>     improved, improve it. Let’s try to keep it simple though.
>
> One problem with API WG members reviewing spec proposals that affect the
> API is finding the specs in the first place across many different
> projects repositories.

I've said for a while now that I would love to have separate 
repositories -- ala the Keystone API in the openstack/identity-api 
repository -- that contains specifications for APIs in a single format 
(APIBlueprint was suggested at one point, but Swagger 2.0 seems to me to 
have more upside).

I also think it would be ideal to have an openstack/openstack-api repo 
that would house guidelines and rules that this working group came up 
with, along with examples of appropriate usage. This repo would function 
very similar to the openstack/governance [1] repo that the TC uses to 
flesh out proposals on community, release management, and governance 
changes.

If people are OK with this idea, I will go ahead and create the repo and 
add the wiki page content as the initial commit, then everyone can 
simply submit patches to the document(s) using the normal Gerrit 
process, and we can iterate on these things using the same tools as 
other repositories.

Best,
-jay

[1] 
https://review.openstack.org/#/q/status:open+project:openstack/governance,n,z

>     I invite everyone who chimed in on the original thread [1] that
>     kicked this off to add themselves as a member committed to making
>     the OpenStack APIs better. I’ve Cc’d everyone who asked to be kept
>     in the loop.
>
>     I already see some cross project summit topics [2] on APIs. But
>     frankly, with the number of people committed to this topic, I’d
>     expect there to be more. I encourage everyone to submit more API
>     related sessions with better descriptions and goals about what you
>     want to achieve in those sessions.
>
> Yea if there is enough content in the API guidelines then perhaps some
> time can be spent on working on resolving any conflicts in the document
> so projects know what direction to head in.
>
> Regards,
>
>   Chris
>
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>