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

[Dean Troyer]

On Tue, Feb 16, 2016 at 1:16 PM, Brant Knudson  wrote:

> This is pretty much the same as your example of specifying a different
> version for the nova API on different requests (except they have a lot more
> than just 2 and 3). We also keep adding routes to v3 each release, so what
> operations are supported keeps changing.
>

The point was more about the client/consumer of the API needing to do it
all at once, which seems to be the perception among the server projects.
If the new features had been incremental that might have been a different
outcome.

dt

-- 

Dean Troyer
dtro...@gmail.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

[Brant Knudson]

On Tue, Feb 16, 2016 at 1:04 PM, Dean Troyer  wrote:

>
>
> On Tue, Feb 16, 2016 at 12:17 PM, Sean Dague  wrote:
>
>> Honestly, doing per API call version switching is probably going to end
>> in tears. HTTP is stateless, so it's allowed, but it will end in tears
>> of complexity as you need to self modify resources before passing them
>> back. Or follow links that don't exist.
>>
>
> Maybe.  But any code that knows it is using a specific version already is
> handling the special cases.  We are trading the speed of implementation for
> the juggling of multiple versions, no matter if they are labelled
> sequentially or via semver.  I've seen places that mixed Identity v2 and v3
> because of the way the APIs worked and were more convenient.  Same problem,
> bigger delta per API rev vs only one rev.
>
> It's also worth looking at the changes we've actually been making here
>> instead of theoretical examples. The amount of effort to make an
>> application use 2.20 instead of 2.1 is pretty minimal.
>
>
> Sure, but there is nothing in place to prevent that contrived example. The
> first time an addition is made of what would have been an extension in the
> past we will be there.  [and no, this is in no way a defense of extensions
> ;).
>
> If Identity had micro-versioned their way between V2 and v3 would the
> other projects been able to convert faster due to not having to do it all
> at once?
>
>
You didn't have to convert from V2 to V3 all at once, and we didn't. I
assume there is still some use of V2 in gate runs in addition to using V3.

Keystone supports the V2 API on /v2.0 and the V3 API on /v3. So you could
make some requests to V2 and other requests to V3. You could get a token
using V2 and use it on V3, or get a token using V3 and use it to do V2
operations. You can't use new V3 features when accessing the V2 API (like
domains).

This is pretty much the same as your example of specifying a different
version for the nova API on different requests (except they have a lot more
than just 2 and 3). We also keep adding routes to v3 each release, so what
operations are supported keeps changing.

 - Brant

dt
>
> --
>
> Dean Troyer
> dtro...@gmail.com
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

[Dean Troyer]

On Tue, Feb 16, 2016 at 12:17 PM, Sean Dague  wrote:

> Honestly, doing per API call version switching is probably going to end
> in tears. HTTP is stateless, so it's allowed, but it will end in tears
> of complexity as you need to self modify resources before passing them
> back. Or follow links that don't exist.
>

Maybe.  But any code that knows it is using a specific version already is
handling the special cases.  We are trading the speed of implementation for
the juggling of multiple versions, no matter if they are labelled
sequentially or via semver.  I've seen places that mixed Identity v2 and v3
because of the way the APIs worked and were more convenient.  Same problem,
bigger delta per API rev vs only one rev.

It's also worth looking at the changes we've actually been making here
> instead of theoretical examples. The amount of effort to make an
> application use 2.20 instead of 2.1 is pretty minimal.


Sure, but there is nothing in place to prevent that contrived example. The
first time an addition is made of what would have been an extension in the
past we will be there.  [and no, this is in no way a defense of extensions
;).

If Identity had micro-versioned their way between V2 and v3 would the other
projects been able to convert faster due to not having to do it all at once?

dt

-- 

Dean Troyer
dtro...@gmail.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

[Sean Dague]

On 02/16/2016 01:13 PM, Dean Troyer wrote:
> On Tue, Feb 16, 2016 at 8:34 AM, Andrew Laski  > wrote:
> ... 
> 
>  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.
> 
> 
> Contrived example alert:
> 
> API version 2.10 adds a pile of parameters to POST /foo/.
> API version 2.35 fixes a problem in GET /bar/details.
> 
> As a client, I might need the 2.35 fix before I have finished
> implementing the big new feature in 2.10 (and intervening) changes.  The
> clients will then use the GLOBAL_API_VERSION=2.7 as a default and use a
> local 2.35 version for the /bar requests.
> 
> This may get fun to manage over time, but allows the client to opt-in to
> new API features without having to swallow the entire thing.  It also
> increases the pressure to make sure the docs are up to snuff for each
> specific API bump.

Honestly, doing per API call version switching is probably going to end
in tears. HTTP is stateless, so it's allowed, but it will end in tears
of complexity as you need to self modify resources before passing them
back. Or follow links that don't exist.

It's also worth looking at the changes we've actually been making here
instead of theoretical examples. The amount of effort to make an
application use 2.20 instead of 2.1 is pretty minimal.

-Sean

-- 
Sean Dague
http://dague.net

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

[Dean Troyer]

On Tue, Feb 16, 2016 at 8:34 AM, Andrew Laski  wrote:
...

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

Contrived example alert:

API version 2.10 adds a pile of parameters to POST /foo/.
API version 2.35 fixes a problem in GET /bar/details.

As a client, I might need the 2.35 fix before I have finished implementing
the big new feature in 2.10 (and intervening) changes.  The clients will
then use the GLOBAL_API_VERSION=2.7 as a default and use a local 2.35
version for the /bar requests.

This may get fun to manage over time, but allows the client to opt-in to
new API features without having to swallow the entire thing.  It also
increases the pressure to make sure the docs are up to snuff for each
specific API bump.

dt

-- 

Dean Troyer
dtro...@gmail.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

[Clint Byrum]

Excerpts from Andrew Laski's message of 2016-02-16 06:34:53 -0800:
> 
> On Tue, Feb 16, 2016, at 07:54 AM, Alex Xu wrote:
> >
> >
> > 2016-02-16 19:53 GMT+08:00 Sean Dague :
> >> 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.
> 
> 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.
> 

It's a trade-off I've wrestled with before, but I think Sean is right,
and the reasons for not doing semver and making compatibility judgements
are still valid. As a user, I would like to have a definitive "this is
how I talk to Nova" version, and that is provided. What it means for
long term viability of that version, I don't know.

What I do think one could _absolutely_ do to build on top of the current
microversion guarantee is write a more pedantic test suite that tries
to use the latest microversion with the previous working microversion's
semantics. On break, that would flag that version for a doc change
and a new version fork of said test suite. Doing that would provide a
monotonically advancing series of micro version windows that represent
compatibility with eachother for at least 

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

[Sean Dague]

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

-- 
Sean Dague
http://dague.net

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

[Andrew Laski]

On Tue, Feb 16, 2016, at 07:54 AM, Alex Xu wrote:
>
>
> 2016-02-16 19:53 GMT+08:00 Sean Dague :
>> 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.

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.


>
>>
>>
-Sean
>>
>>
--
>> 
Sean Dague
>> http://dague.net
>>  
>> 
__
>> 
OpenStack Development Mailing List (not for usage questions)
>> 
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
> 
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
 
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

[Sylvain Bauza]

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

 Regards
 Ghanshyam Mann


 On Mon, Feb 15, 2016 at 12:07 PM, Alex Xu > 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:

GLOBAL_COMPUTE_VERSION = 2.15

... write lots of 

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

[Alex Xu]

2016-02-16 19:53 GMT+08:00 Sean Dague :

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


>
> -Sean
>
> --
> Sean Dague
> http://dague.net
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

[Sean Dague]

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 >> >:
>>>
>>> Regards
>>> Ghanshyam Mann
>>>
>>>
>>> On Mon, Feb 15, 2016 at 12:07 PM, Alex Xu >> > 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 

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

[Sean Dague]

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.

-Sean

-- 
Sean Dague
http://dague.net

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

[Sylvain Bauza]

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


Regards
Ghanshyam Mann


On Mon, Feb 15, 2016 at 12:07 PM, Alex Xu > 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.


-S


>
>
>
> 2016-02-13 4:55 GMT+08:00 Andrew Laski >:
>>
>> 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 

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

[Sylvain Bauza]

Le 16/02/2016 04:09, Alex Xu a écrit :



2016-02-16 9:47 GMT+08:00 GHANSHYAM MANN >:


Regards
Ghanshyam Mann


On Mon, Feb 15, 2016 at 12:07 PM, Alex Xu > 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


>
>
>
> 2016-02-13 4:55 GMT+08:00 Andrew Laski >:
>>
>> 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
  

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

[Alex Xu]

2016-02-16 9:47 GMT+08:00 GHANSHYAM MANN :

> Regards
> Ghanshyam Mann
>
>
> On Mon, Feb 15, 2016 at 12:07 PM, Alex Xu  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.


> >
> >
> >
> > 2016-02-13 4:55 GMT+08:00 Andrew Laski :
> >>
> >> 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.
> >>
> >>
> __
> >> OpenStack Development Mailing List (not for usage questions)
> >> Unsubscribe:
> openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
> >
> >
> >
> >
> __
> > OpenStack Development Mailing List (not for usage questions)
> > Unsubscribe:
> openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
> >
>
> [1]
> 

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

[GHANSHYAM MANN]

Regards
Ghanshyam Mann


On Mon, Feb 15, 2016 at 12:07 PM, Alex Xu  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.

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

>
>
>
> 2016-02-13 4:55 GMT+08:00 Andrew Laski :
>>
>> 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.
>>
>> __
>> OpenStack Development Mailing List (not for usage questions)
>> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>

[1] 
https://github.com/openstack/nova/blob/master/nova/api/openstack/rest_api_version_history.rst

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

[Alex Xu]

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.



2016-02-13 4:55 GMT+08:00 Andrew Laski :

> 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.
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

[Andrew Laski]

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.

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev