Open Stack

On Wed, 18 Jan 2017, Chris Dent wrote:

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

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

There's been a bit of commentary on the review which I'll try to
summarize below. I hope people will join in. There have been plenty
of people talking about this but unless you provide your input
either here or on the review it will be lost.

Most of the people who have commented on the review are generally in
favor of what's there with a few nits on details:

* Header changes should be noted as breaking compatibility/stability
* Changing an error code should be signalled as a breaking change
* The concept of extensions should be removed in favor of "version
   boundaries"
* The examples section needs to be modernized (notably getting rid
   of XML)

There's some concern that "security fixes" (as a justification for a
breaking change) is too broad and could be used too easily.

These all seem to be good practical comments that can be integrated
into a future version but they are, as a whole, based upon a model
of stability based around versioning and "signalling" largely in the
form of microversions. This is not necessarily bad, but it doesn't
address the need to come to mutual terms about what stability,
compatibility and interoperability really mean for both users and
developers. I hope we can figure that out.

If my read of what people have said in the past is correct at least
one definition of HTTP API stability/compatibility is:

    Any extant client code that works should continue working.

If that's correct then a stability guideline needs to serve two
purposes:

* Enumerate the rare circumstances in which that rule may be broken
   (catastrophic security/data integrity problems?).
* Describe how to manage inevitable change (e.g., microversion,
   macroversions, versioned media types) and what "version
   boundaries" are.

And if that's correct then what we are really talking about is
reaching consensus on how (or if) to manage versions. And that's
where the real contention lies. Do we want to commit to
microversions across the board? If we assert that versioning is
something we need across the board then certainly we don't want to
be using different techniques from service to service do we?

If you don't think those things above are correct or miss some
nuance, I hope you will speak up.

Here's some internally-conflicting, hippy-dippy, personal opinion
from me, just for the sake of grist for the mill because nobody else
is yet coughing up:

I'm not sure I fully accept the original assertion. If extant client
code is poor, perhaps because it allows the client to make an
unhealthy demand upon a service, maybe it shouldn't be allowed? If
way A to do something existing, but way B comes along that is better
are we doing a disservice to people's self-improvement by letting A
continue? Breaking stuff can sometimes increase community
engagement, whether that community is OpenStack at large or the
community of users in any given deployment.

Many projects that do not currently have microversions (or other
system) need to manage change in some fashion. It seems backwards to
me that they must subscribe to eternal backwards compatibility when
they don't yet have a mechanism for managing forward motion. I
suppose the benefit of the tag being proposed is that it allows a
project to say "actually, for now, we're not worrying about that;
we'll let you know when we do". In which case they would then have
license to do what they like (and presumably adapt tempest as they
like).

Microversions are an interesting system. They allow for eternal
backwards compatibility by defaulting to being in the past unless
you actively choose a particular point in time or choose to be
always in the present with "latest". When I first started thinking
about this stability concept in the context of OpenStack I felt that
microversions were anti-stability because not only do they help
developers manage change, they give them license to change whenever
they are willing to create a new microversion. That seems contrary
to what I originally perceived as a desire to minimize change.

Further, microversions are a feature that is (as far as I know?)
implemented in a way unique to OpenStack. In other universes some
strategies for versioning are:

* don't ever change
* change aligned with semver of the "product"
* use macroversions in the URL or service definitions
* use versioned media-types (e.g.,
   'application/vnd.os.compute.servers+json; version=1.2') and
   content-negotiation (and keep urls always the same)
* hypermedia

I would guess we have enough commitment to microversions in
production that using something else would be nutbar, but it is
probably worth comparing with some of those systems so that we can
at least clearly state the benefits when making everyone settle in
the same place.

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