Open Stack

On Mon, 13 Oct 2014 10:52:26 -0400
Jay Pipes <jaypipes at gmail.com> wrote:

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

Honestly I don't think we have enough content yet to have much of a
discussion. I started the wiki page

https://wiki.openstack.org/wiki/Governance/Proposed/APIGuidelines

in the hope that people from other projects would start adding
conventions that they use in their projects. I think its fine for the
moment if its contradictory, we just need to gather what projects
currently do (or want to do) in one place so we can start discussing any
contradictions.

So I'd again encourage anyone interested in APIs from the various
projects to just start dumping their project viewpoint in there.

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

I like the idea of a repo and using Gerrit for discussions to resolve
issues. I don't think it works so well when people are wanting to dump
lots of information in initially.  Unless we agree to just merge
anything vaguely reasonable and then resolve the conflicts later when
we have a reasonable amount of content. Otherwise stuff will get lost in
gerrit history comments and people's updates to the document will
overwrite each other.

I guess we could also start fleshing out in the repo how we'll work in
practice too (eg once the document is stable what process do we have
for making changes - two +2's is probably not adequate for something like this).

Regards,

Chris

> 
> 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
> >
> 
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev