Open Stack

On Mon, 13 Oct 2014 22:20:32 -0400
Jay Pipes <jaypipes at gmail.com> wrote:

> On 10/13/2014 07:11 PM, Christopher Yeoh wrote:
> > 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.
> 
> Actually, I don't care all that much about what projects *currently*
> do. I want this API working group to come up with concrete guidelines
> and rules/examples of what APIs *should* look like.

What projects currently do gives us a baseline to work from. It also
should expose where we have currently have inconsistencies between
projects.

And whilst I don't have a problem with having some guidelines which
suggest a future standard for APIs, I don't think we should be
requiring any type of feature which has not yet been implemented in
at least one, preferably two openstack projects and released and tested
for a cycle. Eg standards should be lagging rather than leading.

> > So I'd again encourage anyone interested in APIs from the various
> > projects to just start dumping their project viewpoint in there.
> 
> I went ahead and just created a repository that contained all the
> stuff that should be pretty much agreed-to, and a bunch of stub topic 
> documents that can be used to propose specific ideas (and get
> feedback on) here:
> 
> http://github.com/jaypipes/openstack-api
> 
> Hopefully, you can give it a look and get a feel for why I think the 
> code review process will be better than the wiki for controlling the 
> deliverables produced by this team...

I think it will be better in git (but we also need it in gerrit) when
it comes to resolving conflicts and after we've established a decent
document (eg when we have more content). I'm just looking to make it
as easy as possible for anyone to add any guidelines now. Once we've
actually got something to discuss then we use git/gerrit with patches
proposed to resolve conflicts within the document.

> 
> > 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).
> 
> We can make it work exactly like the openstack/governance repo, where 
> ttx has the only ability to +2/+W approve a patch for merging, and he 
> tallies a majority vote from the TC members, who vote -1 or +1 on a 
> proposed patch.
> 
> Instead of ttx, though, we can have an API working group lead
> selected from the set of folks currently listed as committed to the
> effort?

Yep, that sounds fine, though I don't think a simple majority is
sufficient for something like api standards. We either get consensus
or we don't include it in the final document.

Chris