Open Stack

2014-10-13 16:52 GMT+02:00 Jay Pipes <jaypipes at gmail.com>:
> 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.

Thanks Jay,

I much prefer this idea.
I concerned how to handle API rule conflicts if using a wiki page.
eg: Someone prefer CamelCase names as attributes but the other does snake_case.
If using gerrit, we can propose favorite rules as each commit and we can
discuss them on it. That would be nice to build a consensus for the rules.

Thanks
Ken