Open Stack

"Kevin L. Mitchell" <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