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

Sylvain Bauza sbauza at redhat.com
Tue Feb 16 13:12:50 UTC 2016

Le 16/02/2016 13:01, Sean Dague a écrit :
> On 02/16/2016 03:33 AM, Sylvain Bauza wrote:
>> Le 16/02/2016 09:30, Sylvain Bauza a écrit :
>>> Le 16/02/2016 04:09, Alex Xu a écrit :
>>>> 2016-02-16 9:47 GMT+08:00 GHANSHYAM MANN <ghanshyammann at gmail.com
>>>> <mailto:ghanshyammann at gmail.com>>:
>>>>      Regards
>>>>      Ghanshyam Mann
>>>>      On Mon, Feb 15, 2016 at 12:07 PM, Alex Xu <soulxu at gmail.com
>>>>      <mailto:soulxu at gmail.com>> wrote:
>>>>      > If we support 2.x.y, when we bump 'x' is a problem. We didn't
>>>>      order the API
>>>>      > changes for now, the version of API change is just based on the
>>>>      order of
>>>>      > patch merge. For support 2.x.y, we need bump 'y' first for
>>>>      back-compatible
>>>>      > changes I guess.
>>>>      >
>>>>      > As I remember, we said before, the new feature is the
>>>>      motivation of user
>>>>      > upgrade their client to support new version API, whatever the
>>>>      new version is
>>>>      > backward compatible or incompatible. So I guess the initial
>>>>      thinking we hope
>>>>      > user always upgrade their code than always stop at old version?
>>>>      If we bump
>>>>      > 'x' after a lot of 'y', will that lead to user always stop at
>>>>      'x' version?
>>>>      > And the evolution of api will slow down.
>>>>      >
>>>>      > Or we limit to each release cycle. In each release, we bump 'y'
>>>>      first, and
>>>>      > then bump 'x'. Even there isn't any back-incompatible change in
>>>>      the release.
>>>>      > We still bump 'x' when released. Then we can encourage user
>>>>      upgrade their
>>>>      > code. But I still think the back-incompatible API change will
>>>>      be slow down
>>>>      > in development, as it need always merged after back-compatible
>>>>      API change
>>>>      > patches.
>>>>      Yea that true and will be more complicated from development
>>>>      perspective which leads to slow down the evolution of API changes.
>>>>      But if we support x.y then still we can change x at any time back
>>>>      in-comp changes happens(i mean before y also)? Or I may not be
>>>>      getting
>>>>      the issue you mentioned about always bump y before x.
>>>> If the back-incompatible change merged before back-compatible change,
>>>> then 'y' become useless. For example, the initial version is 2.1.0,
>>>> then we have 3 back-comp and 3 in-comp changes, and we are unlucky,
>>>> in-comp changes merged first, then we get version 2.4.3, then if user
>>>> want to use those back-comp changes, it still need upgrade those 3
>>>> in-comp changes.
>>>>      I like the idea of distinguish the backward comp and in-comp changes
>>>>      with x and y which always gives clear perspective about changes.
>>>>      But it should not lead users to ignore y. I mean some backward comp
>>>>      changes which are really good gets ignored by users as they start
>>>>      look
>>>>      at the x only.
>>>>      For example- "adding attribute in resource representation" is back
>>>>      comp change (if so) and if that is added as y then, it might get
>>>>      ignored by users.
>>>>      Another way to clearly distinguish backward comp and in-comp changes
>>>>      is through documentation which was initially discussed during
>>>>      microversion specs. Currently doc has good description about each
>>>>      changes but not much clear way about backward comp or not.
>>>>      Which we can do by adding a clear flag [Backward Compatible/
>>>>      Incompatible] for each version in doc [1]-
>>>> +1 for doc the change is backward comp or not.
>>> I'm not usually good at thinking API references, but something pinged
>>> my brain so lemme know if that's terrible or not.
>>> Why not semantically say that :
>>>   - if the API microversion is a ten, then it's a non-backwards
>>> compatible change
>>>   - if not, it's backwards-compatible
>>> If you are like with the version #29 and add a new
>>> backwards-compatible version, then it would be #31 (and not #30).
>>> That way, you would still have a monotonic increase, which I think was
>>> an agreement when discussing about microversioning, but it would help
>>> the users which would know the semantics and just look whether a ten
>>> is between the version they use and the version they want (and if so,
>>> if it was implemented).
>>> Call me dumb, it's just a thought.
>>> -Sylvain
>> One slight improvement could be to consider hundreds and not tens for
>> major versions. That would leave 99 'minor' versions between majors,
>> which I think is doable.
> No, please no.
> https://dague.net/2015/06/05/the-nova-api-in-kilo-and-beyond-2/ - the
> backwards compatibility fallacy. We've been here before during the
> design of the system. Declaring additional semantic meaning to version
> numbers is just complexity for very little gain.
> It also means we're going to have another hard to figure out thing with
> every change. Is this backwards compatible or not? Remember, we have
> strict json schema checking, so adding a parameter is not backwards
> compatible.
> Everyone thinks they know what's a compatible change, until they
> release, then break people using the interface in ways that were
> unexpected (see: weekly breaks from pypi).
> The expectation is that client programs are going to do the following:
> ... write lots of nova code.
> When the team wants a new feature from Nova, they'll bump that explicitly.
> 	-Sean

Fair point, I didn't want to break agreements. Saying that each 
microversion is not backwards-compatible seems fine by me, since users 
can stay with a microversion for their use.


More information about the OpenStack-dev mailing list