[openstack-dev] [all] [tc] [api] refreshing and revalidating api compatibility guidelines

Chris Dent cdent+os at anticdent.org
Tue Jan 24 17:39:19 UTC 2017


On Mon, 23 Jan 2017, Sean Dague wrote:

> We all inherited a bunch of odd and poorly defined behaviors in the
> system we're using. They were made because at the time they seemed like
> reasonable tradeoffs, and a couple of years later we learned more, or
> needed to address a different use case that people didn't consider before.

Thanks, as usual, for providing some well considered input Sean. I
think it captures well what we could describe as the "nova
aspirational model for managing change" which essentially means:

* don't change stuff unless you have to
* when you do change stuff, anything, use microversions to signal

This is a common position and I suspect if we were to use the
voices that have spoken up so far to form the new document[1] then
it would codify that, including specifying microversions as the
technology for managing boundaries.

That could very well be fine, but we have evidence that:

* some projects don't yet use microversions in their APIs
* some projects have no intention of using microversions or at least
   have internal conflict about doing so
* some projects would like to change things (irrespective of
   microversions)

What do we do about that? That's what I think we could be working
out here, and why I'm persisting in dragging this out. There's no
point making rules that a significant portion of the populace have
no interest in following.

So the options seem to be:

* codify the two rules above as the backbone for the
   api-compatibility assertion tag and allow several projects to not
   assert that, despite an overall OpenStack goal

* keep hashing things out for a bit longer until either we have
   different rules so we have more projects liking the rules or we
   justify the rules until we have more projects accepting them

More in response to Sean below, not to contradict what he's saying
but in the ever-optimistic hope of continuing and expanding the
conversation to get real rather than enforced consensus.

> If you don't guaruntee that existing applications will work in the
> future (for some reasonable window of time), it's a massive turn off to
> anyone deciding to use this interface at all. You suppress your user base.

I think "reasonable window of time" is a key phrase here that
perhaps we can build into the guidelines somewhat. The problems of
course are that some clouds will move forward in time at different
rates and as Sean has frequently pointed out, time's arrow is not
unidirectional in the universe of many OpenStack clouds.

To what extent is the HEAD of OpenStack responsible to OpenStack two
or three years back?

Also, when suppressing or not suppressing which user base is more
important? The users that exist now or the users to come? This may
sound like a snarky or idle question, but it's a real one: Is it
true that we do, as a general rule, base our development on existing
users and not people who have chosen not to use "the product" for
some reason?

> This is a real issue. A real issue raised by users and other project
> teams. I do understand that in other contexts / projects that people
> have been involved in, this may not have been considered an issue. But I
> would assert it is one here.

I don't think anyone disagrees with it being a real issue. Perhaps
it would be more correct to say "I agree with your assertion". I
also, however, assert that we can learn from other approaches. Not
so that we can use different approaches, but so that we can clarify
and evolve the approaches we do use so that people more fully
understand the reasons, edge cases, etc. For some the problem (and
solutions) are very well understood and accepted, for others not so
much. The compare and constrast technique is a time honored and
tested way of expanding the mind.

> So before reopening the exploration of approaches (or the need to do
> anything at all), we should probably narrow the focus of whether
> guaruntees to the user that their existing code will continue to work is
> something that we need / want. I don't see any new data coming into our
> community that this is less important than it was 4 years ago.

But we do have some data (recent glance visibility situation) that
sometimes changing stuff that violates the letter of the law (but
not really the spirit?) causes indecision and confusion when
evaluating changes. Are we going to declare this okay because glance
doesn't (and can't (yet) if we assert microversions) assert api
stability support?

We also have endless data that changing APIs is part and parcel of
what we do and that change of any kind is part and parcel of living
in the real world. I think even if we are maintaining that backwards
stability is critical we need to think about the cognitive cost of
multiple microversions to users. They are under no obligation to use
the new features or the bug fixes, but they do represent fairly
constant change that you only get access to if you choose to be
aware of microversions or use particular versions of supplied
clients.

A rough calculation suggests the compute API went through 25
microversions in 2016. A part of this is because each individual
feature or fix is a new version (a good thing!) instead anything
resembling a composed release, but it is still a lot of change. Your
old school HTTP API person would say "make your resources, make your
representations, stop".  We're not like that. And presumably can't
be like that, but it is something to think about.

Without further input, I'll make a pass by the end of the week at
codifying what's described at the start of this message in the
review but I would prefer to see more input first. Not because I
think we'll end up with something different (though we may) but
because more input from more than the usual suspects is a good
thing.

[1] https://review.openstack.org/421846
-- 
Chris Dent                 ¯\_(ツ)_/¯           https://anticdent.org/
freenode: cdent                                         tw: @anticdent


More information about the OpenStack-dev mailing list