Open Stack

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 <corvus at inaugust.com<mailto:corvus at inaugust.com>> wrote:

"Kevin L. Mitchell" <kevin.mitchell at rackspace.com<mailto:kevin.mitchell at rackspace.com>> 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: OpenStack-dev-request at lists.openstack.org<mailto:OpenStack-dev-request at lists.openstack.org>?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20150206/54c3c6f3/attachment.html>