Open Stack

On Tue, 14 Oct 2014 05:27:21 +0200
"Ken'ichi Ohmichi" <ken1ohmichi at gmail.com> wrote:

> 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.

So for now I'd suggest just adding both - CamelCase and snake_case as
possible guidelines. Once we have all these (possibly conflicting) ideas
in the document then we move it to git/gerrit and propose patches to
resolve any conflicts or remove bits that people don't like.

Eg. I'm suggesting we work from a large document where everyone gets to
throw their opinions in and cut it down rather than start from nothing
and try to build it up patch by patch. I think its a better way for
ensuring people see other people's ideas and where they conflict with
other people's.

Regards,

Chris