Top posting to wrap this up. During the last API WG meeting [1] we discussed this topic. Of the 8 people who voted, it was unanimous and we agreed [2] to use the api-wg repo to write our guidelines.
This email thread wasn’t conclusive on the subject so we’ll be moving forward with the result of the vote at the meeting. Unless there’s a strong objection or disagreement with my analysis of the above, the API WG will move forward and use the api-wg repo. Thanks, Everett [1] http://eavesdrop.openstack.org/meetings/api_wg/2015/api_wg.2015-02-05-00.00.html [2] http://eavesdrop.openstack.org/meetings/api_wg/2015/api_wg.2015-02-05-00.00.log.html#l-205 On Jan 31, 2015, at 10:36 AM, James E. Blair <[email protected]<mailto:[email protected]>> wrote: "Kevin L. Mitchell" <[email protected]<mailto:[email protected]>> writes: On Fri, 2015-01-30 at 22:33 +0000, Everett Toews wrote: It was suggested that the API WG use the openstack-specs [1] and/or the api-wg [2] repo to publish its guidelines. We’ve already arrived at the consensus that we should only use 1 repo [3]. So the purpose of this thread is to decide... Should the API WG use the openstack-specs repo or the api-wg repo? Let’s discuss. Well, the guidelines are just that: guidelines. They don't implicitly propose changes to any OpenStack projects, just provide guidance for future API changes. Thus, I think they should go in a repo separate from any of our *-specs repos; to me, a spec provides documentation of a change, and is thus independent of the guidelines. Hi, As a user of OpenStack I find the APIs inconsistent with each other. My understanding is that the API wg hopes to change this (thanks!). As the current reality is almost certainly not going to be completely in alignment with the result of the wg, I think that necessarily there will be a change in some software. Consider the logging spec -- it says "logs should look like this and use these levels under these circumstances". Many projects do not match that at the moment, and will need changes. I can imagine something similar with the API wg. Perhaps with APIs, things are a bit more complex and in addition to a cross-project spec, we would need individual project specs to say "in order to get foo's API consistent with the guidelines, we will need to make these changes and support these behaviors during a deprecation period". If that's the case, we can certainly put that level of detail in an individual project spec repo while keeping the cross-project spec focused on what things _should_ look like. At any rate, I think it is important that eventually the result of the API wg causes technical change to happen, and as such, I think the openstack-specs repo seems like a good place. I believe that openstack-specs also provides a good place for reference documentation like this (and logging guidelines, etc) to be published indefinitely for current and new projects. -Jim __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: [email protected]<mailto:[email protected]>?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
__________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: [email protected]?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
