Open Stack

On 10/14/2014 12:52 AM, Christopher Yeoh wrote:
> 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.

Sure.

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

What about "features" in some of our APIs that are *not* preferable? For 
instance: API extensions.

I think we've seen where API extensions leads us. And it isn't pretty. 
Would you suggest we document what a Nova API extension or a Neutron API 
extension looks like and then propose, for instance, not to ever do it 
again in future APIs and instead use schema discoverability?

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

Of course it would be in Gerrit. I just put it up on GitHub first 
because I can't just add a repo into the openstack/ code namespace... :)

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

Sure, those are details we can debate... super-majority, majority, 
complete consensus. Whatever works, I'm cool with.

Best,
-jay