<div dir="ltr"><div class="gmail_extra"><br><div class="gmail_quote">On Tue, Jul 28, 2015 at 6:05 AM, Jim Rollenhagen <span dir="ltr"><<a href="mailto:jim@jimrollenhagen.com" target="_blank">jim@jimrollenhagen.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">[snip]<br>
<br>
It seems to me we have a few options here:<br>
<br>
1) Default the python client and CLI to the earliest supported version.<br>
This will never break users by default.<br>
<br>
2) Default the python client and CLI to use the special version<br>
'latest'. This will always use the latest API version, and always<br>
break people when a new server version (that is not backwards<br>
compatible) is deployed.<br>
<br>
3) Do what Nova does[1]. Default CLI to latest and python client to<br>
earliest. This assumes that CLI is typically used for one-time commands<br>
(and it isn't a big deal if we break a one-off command once), and the<br>
python client is used for applications.<br>
<br>
4) Require a version to use the client at all. This would be a one-time<br>
break with how applications initialize the client (perhaps we could fall<br>
back to the earliest version or something for a deprecation period).<br>
This isn't a great user experience, however, it's the best way to get<br>
users to think about versioning. And no, "this requires typing another<br>
argument every time!" is not a valid argument against this; we already<br>
require a number of arguments, anyone sane doesn't type --ironic-api-url<br>
or --os-username every time they use the client.<br>
<br>
5) Do what we're doing now. Bump the client's default version with every<br>
release. This mostly hides these versions from end users, and in general<br>
those users probably won't know they exist. And then we run into<br>
arguments every time we want to make a breaking change to the API. :)<br>
<br>
I think I like option 1 or 3 the best. I certainly don't like option 5<br>
because we're going to break users every time we release a new client.<br>
<br>
What do other folks think we should do?<br></blockquote><div><br></div><div>Thanks jroll for bringing this up!</div><div><br></div><div>Isn't the problem here that we're treating breaking and non-breaking changes similarly?<div><br></div><div>Didn't we previously say that major backward incompatible changes should require a major version bump?</div></div><div><br></div><div>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?</div><div><br></div><div>I think we want the latest version of the API, used by the client and server, that is backwards compatible i.e. min(latest client version, latest server version).  As developers we want the latest version of our code out there.  As operators and users we want the latest (backward compatible) features and the bug fixes, but we don't want to rewrite how we interface to the software.</div><div><br></div><div>But if a version is explicitly specified, that should be used instead i.e. we should support version pining so that operators can gracefully upgrade when it's right for them (assuming the server still supports that version)</div><div><br></div><div>But the question remains, "What version of the API do we want to ship when we ship a major Ironic release?" (whenever that is now[1] :-P ) Or phrased differently, "How do we advance versions from release to release?".  I think the answer to this is that we default to the latest stable major API version at the point of release.  That should be the default for client and server, and shouldn't discount anyone from using older clients with newer servers and vice versa due to the presence of version negotiation.</div><div><br></div><div>Hope this helps,</div><div><br></div><div>Michael...</div><div><br></div><div>[1] <a href="https://github.com/openstack/ironic-specs/blob/master/specs/liberty/feature-based-releases.rst">https://github.com/openstack/ironic-specs/blob/master/specs/liberty/feature-based-releases.rst</a><br></div><div>-- <br></div></div><div class="gmail_signature"><div dir="ltr"><div>Michael Davies   <a href="mailto:michael@the-davies.net" target="_blank">michael@the-davies.net</a><br><span style="color:rgb(80,0,80);font-size:12.8000001907349px">Rackspace Cloud Builders Australia</span><br></div></div></div>
</div></div>