Open Stack

Last night in the TC meeting a topic[1] was a review[2] to
introduce a new tag 'assert:supports-api-compatibility' which:

     defines the base expectations and requirements for a stable REST
     API provided by a service

The tag document uses an API guideline, "Evaluating API Changes"[3],
as the reference for those expectations. That guideline is out of
date (see below) and needs to be refreshed and revalidated with
attention to modern concerns. I've started a review

     https://review.openstack.org/#/c/421846/

within the api-wg to evolve the existing document into a new one
that provides an effective guideline for what API compatibility and
stability mean and how to make it happen in a service.

The review starts with the original text. The hope is that
commentary here in this thread and on the review will eventually
lead to the best document.

There are reasons for doing it that way, instead of starting from a
fresh new proposal or doing piecemeal edits on the existing
document:

* API compatibility over time is a fundamental aspect of the
   OpenStack interoperability story. We not only need to get it
   right, we need to make sure we get it understandable.

* We can't write an accurate document if we don't first have the
   conversation which ensures we are all talking about the same thing
   and using the same meanings when we use the same words. Starting
   the evaluation from a new document authored by a single person or
   an existing document predisposes the discussion.

What are the next steps? If you are engaged by this topic then:

* Read all these linked things to get some context.
* Comment in response to this email or on the review[0] with your
   thoughts, concerns, ideas.

The questions we are trying to answer include (but are not limited
to):

* What are API compatibility, stability and maturity?
* Why do we want those things? Or, in other words, why is it bad to
   not have those things?
* What are the situations, if any, when a project can legitimately
   claim to not follow stability (e.g., being new, alpha, etc)?
* When an API claims stability, what changes are considered
   acceptable or unacceptable?
* [Anything else you think is important.]

It's not necessarily the case that the answers to all these
questions will end up in the document, but we do need to know the
answers in order to make the document good. It may seem to some
participants that we've already answered a lot of these questions in
the past. That's fine. The point here is to revalidate and refresh.

If you're confused about where to put your thoughts, default to here
in email where we should be working to build a consensus (through
fairly meandering conversation) about the overall topic. The review
should be more about concrete additions or changes to the document
or annotations to indicate where it is wrong or has failed to
reflect the discussion here correctly.

I will corral the responses and keep the document under review up to
date. I'm away from my computer tomorrow and Friday so I hope that
will provide some time for some content to build up without me
injecting too many of my own opinions.

For a little more background: In the discussion last night I pointed
out that (at least some members of) the API-WG have some concerns
with that document but haven't yet had an opportunity to address
them.

In part the concerns came from the document's use as the letter of
the law in the discussions related to the glance visibility
changes[4]. We need to make sure that if we are wielding the
document in that fashion it is correct with regard to modern
concerns and properly sets the stage for why API compatibility is
important. I committed to starting a process to clear things up.

The first thing I noticed was that the guideline was last changed in
2015, its initial commit into the api-wg repo. The content was fully
based on wiki content that had had no substantial changes since 2012
and reflects some things that were normal then (like extensions)
which are not now. The second thing I noticed was that the document
doesn't really contextualize why API compatibility is important.

[0] Collaborative review to make new guideline
     https://review.openstack.org/#/c/421846/

[1] #topic Introduce assert:supports-api-compatibility
     http://eavesdrop.openstack.org/meetings/tc/2017/tc.2017-01-17-20.00.log.html#l-181

[2] assert:supports-api-compatbility review
     https://review.openstack.org/#/c/418010/

[3] "Evaluating API Changes" API guideline
     http://specs.openstack.org/openstack/api-wg/guidelines/evaluating_api_changes.html

[4] Email thread about glance visibility with links elsewhere
     http://lists.openstack.org/pipermail/openstack-dev/2017-January/109678.html
     Related tempest test
     https://review.openstack.org/#/c/414261/

-- 
Chris Dent                 ¯\_(ツ)_/¯           https://anticdent.org/
freenode: cdent                                         tw: @anticdent