Open Stack

On 07/30/2015 12:55 AM, Michael Davies wrote:
>
> On Tue, Jul 28, 2015 at 6:05 AM, Jim Rollenhagen <jim at jimrollenhagen.com
> <mailto:jim at jimrollenhagen.com>> wrote:
>
>     [snip]
>
>     It seems to me we have a few options here:
>
>     1) Default the python client and CLI to the earliest supported version.
>     This will never break users by default.
>
>     2) Default the python client and CLI to use the special version
>     'latest'. This will always use the latest API version, and always
>     break people when a new server version (that is not backwards
>     compatible) is deployed.
>
>     3) Do what Nova does[1]. Default CLI to latest and python client to
>     earliest. This assumes that CLI is typically used for one-time commands
>     (and it isn't a big deal if we break a one-off command once), and the
>     python client is used for applications.
>
>     4) Require a version to use the client at all. This would be a one-time
>     break with how applications initialize the client (perhaps we could fall
>     back to the earliest version or something for a deprecation period).
>     This isn't a great user experience, however, it's the best way to get
>     users to think about versioning. And no, "this requires typing another
>     argument every time!" is not a valid argument against this; we already
>     require a number of arguments, anyone sane doesn't type --ironic-api-url
>     or --os-username every time they use the client.
>
>     5) Do what we're doing now. Bump the client's default version with every
>     release. This mostly hides these versions from end users, and in general
>     those users probably won't know they exist. And then we run into
>     arguments every time we want to make a breaking change to the API. :)
>
>     I think I like option 1 or 3 the best. I certainly don't like option 5
>     because we're going to break users every time we release a new client.
>
>     What do other folks think we should do?
>
>
> Thanks jroll for bringing this up!
>
> Isn't the problem here that we're treating breaking and non-breaking changes
> similarly?
>
> Didn't we previously say that major backward incompatible changes should require
> a major version bump?
>
> What if we adopted a semver or similar scheme for API versioning?  What if we
> required 'Major' (in Major.Minor.Patch) to increment for a backwards
> incompatible change?  In our current tooling this would be hard, but is it what
> we should be doing?  Is this the root of the problem?

It seems to me that this is basically microversions except that it gives you the 
added knowledge that a backwards incompatible change has occurred.  I'm not 
quite clear how that makes any difference though.

For applications linking against libraries, the major version implies a 
dependency--the application requires that specific major version of the library, 
and a minor version at least as good as what it was built against.  How would 
that translate to a REST API?  Would the client code need to special-case every 
major version that they plan on supporting?  What about minor versions that add 
functionality--if we special-case those as well then we're basically back to 
microversions.

Chris