On Tue, 14 Oct 2014 05:27:21 +0200 "Ken'ichi Ohmichi" <ken1ohmi...@gmail.com> wrote:
> 2014-10-13 16:52 GMT+02:00 Jay Pipes <jaypi...@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 _______________________________________________ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev