Open Stack

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.

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

Best,
-jay