[openstack-dev] [Ironic] When to bump the microversion?

Sean Dague sean at dague.net
Thu Jun 4 15:03:20 UTC 2015

On 06/04/2015 10:50 AM, Dmitry Tantsur wrote:
> On 06/04/2015 04:40 PM, Ruby Loo wrote:
>> Hi,
>> In Kilo, we introduced microversions but it seems to be a
>> work-in-progress. There is an effort now to add microversion into the
>> API-WG's guidelines, to provide a consistent way of using microversions
>> across OpenStack projects [1]. Specifically, in the context of this
>> email, there is a proposed guideline for when to bump the microversion
>> [2].
> As I understand this guideline tells to bump microversion on every
> change which I strongly -1 as usual. Reason: it's bump for the sake of
> bump, without any direct benefit for users (no, API discoverability is
> not one, because microversion do not solve it).
> I'll post the same comment to the guideline.

Backwards compatible API adds with no user signaling is a fallacy
because it assumes the arrow of time flows only one way.

If at version 1.5 you have a resource that is

foo {
  "bar": ...

And then you decide you want to add another attribute

foo {
  "bar": ...
  "baz": ...

And you don't bump the version, you'll get a set of users that use a
cloud with baz, and incorrectly assume that version 1.5 of the API means
that baz will always be there. Except, there are lots of clouds out
there, including ones that might be at the code commit before it was
added. Because there are lots of deploys in the world, your users can
effectively go back in time.

So now your API definition for version 1.5 is:

"foo, may or may not contain baz, and there is no way of you knowing if
it will until you try. good luck."

Which is pretty aweful.

Looking at your comments in the WG repo you also seem to only be
considering projects shipped at Major release versions (Kilo, Liberty).
Which might be true of Red Hat's product policy, but it's not generally
true that all clouds are at a release boundary. Continous Deployment of
OpenStack has been a value from Day 1, and many public clouds are not
using releases, but are using arbitrary points off of master. A
microversion describes when a changes happens so that applications
writers have a very firm contract about what they are talking to.


Sean Dague

More information about the OpenStack-dev mailing list