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

    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.

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@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


_______________________________________________
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Reply via email to