On 10/14/2014 12:52 AM, Christopher Yeoh wrote:
On Mon, 13 Oct 2014 22:20:32 -0400
Jay Pipes <jaypi...@gmail.com> wrote:
On 10/13/2014 07:11 PM, Christopher Yeoh wrote:
On Mon, 13 Oct 2014 10:52:26 -0400
Jay Pipes <jaypi...@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
_______________________________________________
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
