[openstack-dev] [Nova] Should we signal backwards incompatible changes in microversions?

Sean Dague sean at dague.net
Tue Feb 16 15:17:39 UTC 2016

On 02/16/2016 09:34 AM, Andrew Laski wrote:
> On Tue, Feb 16, 2016, at 07:54 AM, Alex Xu wrote:
>> 2016-02-16 19:53 GMT+08:00 Sean Dague <sean at dague.net
>> <mailto:sean at dague.net>>:
>>     On 02/12/2016 03:55 PM, Andrew Laski wrote:
>>     > Starting a new thread to continue a thought that came up in
>>     > http://lists.openstack.org/pipermail/openstack-dev/2016-February/086457.html.
>>     > The Nova API microversion framework allows for backwards compatible and
>>     > backwards incompatible changes but there is no way to programmatically
>>     > distinguish the two. This means that as a user of the API I need to
>>     > understand every change between the version I'm using now and a new
>>     > version I would like to move to in case an intermediate version changes
>>     > default behaviors or removes something I'm currently using.
>>     >
>>     > I would suggest that a more user friendly approach would be to
>>     > distinguish the two types of changes. Perhaps something like 2.x.y where
>>     > x is bumped for a backwards incompatible change and y is still
>>     > monotonically increasing regardless of bumps to x. So if the current
>>     > version is 2.2.7 a new backwards compatible change would bump to 2.2.8
>>     > or a new backwards incompatible change would bump to 2.3.8. As a user
>>     > this would allow me to fairly freely bump the version I'm consuming
>>     > until x changes at which point I need to take more care in moving to a
>>     > new version.
>>     >
>>     > Just wanted to throw the idea out to get some feedback. Or perhaps this
>>     > was already discussed and dismissed when microversions were added and I
>>     > just missed it.
>>     Please no.
>>     We specifically stated many times that microversions aren't
>>     semver. Each
>>     version is just that.
>>     Semver only makes sense when you are always talking to one
>>     installation,
>>     and the version numbers can only increase. When your code retargets to
>>     multiple installations version numbers can very easily go
>>     backwards. So
>>     unless a change in compatible forward and backwards, it's a breaking
>>     change for someone.
>> indeed, learned this point.
> Fair enough, I wasn't thinking a lot about moving between installations
> just that we've hidden information within one installation.
> Since any change except one that is backwards and forwards compatible is
> a breaking change for users of multiple clouds what is essentially being
> said is that we have a new API with every microversion. Given that I
> wonder if we shouldn't make a stronger statement that the API differs,
> as in why even have a 2. prefix which implies that 2.x has some relation
> to 2.x+1 when it doesn't.

That was in the original conversations, to make it a monotonically
increasing single number. It got shot down somewhere in the middle of it
all, and I can't remember why now.

> It was mentioned elsewhere in the thread that we have a hard time
> knowing what's going to end up being compatible or not before it's
> released. This seems like something we should be able to determine and
> indicate somehow, even just through docs, otherwise we're passing that
> burden on to users to determine for themselves.
> I very much like that microversions have enabled development to move
> forward on the API without the mess of extensions that we had
> previously. I fear that we have no real measurement of the cost of
> consuming the API under this new scheme. It's easy enough to think that
> users will just read the docs and carefully consider every version
> increment that they want to consume but when they've been on version 2.7
> for a while and a new thing comes out in 2.35 that they want they need
> to fully digest the implications of all 27 intervening versions purely
> through docs and with the understanding that literally almost anything
> about the semantics can have changed. So while I love the freedom that
> it provides to developers I think it would be useful to have a small set
> of constraints in place that helps users. Of course all of my ideas have
> been duds so far and perhaps that's because I'm imagining future
> scenarios that won't come to pass or that we don't care about. But
> something has me concerned and I can't quite get my finger on it.

I definitely understand that concern. And I also don't think we've
really come up with a good way of getting docs to users yet (which is
not hugely different than the extension problem before).


Sean Dague

More information about the OpenStack-dev mailing list