<div dir="ltr">I'm going to reply to several emails in this thread - but separately, because they're from separate people and with separate POV, and I think it will be even harder to discern what I'm saying if I merge the contexts before replying... so bear with me ...<br><br><br><div class="gmail_quote"><div dir="ltr">On Mon, Jul 27, 2015 at 1:36 PM Jim Rollenhagen <<a href="mailto:jim@jimrollenhagen.com">jim@jimrollenhagen.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Hi friends.<br>
<br>
Ironic implemented API "micro" versions in Kilo. We originally did this<br>
to allow for breaking changes in the API while allowing users to opt in<br>
to the breakage.<br>
<br>
Since then, we've had a "default version" for our client that we bump to<br>
something sensible with each release. Currently it is at 1.8.<br>
Negotiation is done with the server to figure out what is supported and<br>
adjust accordingly.<br>
<br>
Now we've landed a patch[0] with a new version (1.11) that is not<br>
backward compatible. </blockquote><div><br></div><div>No, that patch isn't backwards compatible -- ** but it could be **.</div><div><br></div><div>That's the biggest reason that I disagree with what's proposed here -- it would be trivially easy for us to make this change be backwards compatible by allowing an optional parameter in the POST command that changes the initial state of a node from AVAILABLE to ENROLL.</div><div><br></div><div>Allow users to opt-in to the new behavior *and* discover its presence from the API version header. There is simply no reason for this to be a breaking change. I simply do not understand how folks think "we can version the API" means "we should break users even when we don't have to".</div><div><br></div><div>Anyway, I've said that before. There are other points I want to respond to as well, so I'll carry on...</div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">It causes newly added Node objects to begin life in<br>
the ENROLL state, rather than AVAILABLE. This is a good thing, and<br>
people should want this! However, it is a breaking change. Automation<br>
that adds nodes to Ironic will need to do different things after the<br>
node-create call.<br>
<br>
Our API versioning scheme makes this opt-in (by specifying the API<br>
version). However, some folks have a problem with releasing this change<br>
as-is. The logic is that we might release a client that defaults to 1.11<br>
or higher, or the user may request 1.12 later to get a new feature, thus<br>
breaking their application that enrolls nodes.<br></blockquote><div><br></div><div>The current approach is supposed to allow users "<span style="color:rgb(62,67,73);font-family:Arial,sans-serif;font-size:14.3999996185303px;line-height:21.5999984741211px">to make use of new features as they become available, while also ensuring they don’t break due to incompatibilities" [0] However, you're advocating against providing that right now -- if a user wants a feature added in 1.12, they will be forced to accept the breaking change in 1.11.</span></div><div><span style="color:rgb(62,67,73);font-family:Arial,sans-serif;font-size:14.3999996185303px;line-height:21.5999984741211px"><br></span></div><div><span style="color:rgb(62,67,73);font-family:Arial,sans-serif;font-size:14.3999996185303px;line-height:21.5999984741211px">While I have proposed some changes to our specification for API versioning [1], removing this statement of intent is not one of the changes I've proposed.</span></div><div><span style="color:rgb(62,67,73);font-family:Arial,sans-serif;font-size:14.3999996185303px;line-height:21.5999984741211px"><br></span></div><div><span style="color:rgb(62,67,73);font-family:Arial,sans-serif;font-size:14.3999996185303px;line-height:21.5999984741211px">[0] </span><font color="#3e4349" face="Arial, sans-serif"><span style="font-size:14.3999996185303px;line-height:21.5999984741211px"><a href="http://specs.openstack.org/openstack/ironic-specs/specs/kilo/api-microversions.html#problem-description">http://specs.openstack.org/openstack/ironic-specs/specs/kilo/api-microversions.html#problem-description</a></span></font></div><div><font color="#3e4349" face="Arial, sans-serif"><span style="font-size:14.3999996185303px;line-height:21.5999984741211px"><br></span></font></div><div><font color="#3e4349" face="Arial, sans-serif"><span style="font-size:14.3999996185303px;line-height:21.5999984741211px">[1] <a href="https://review.openstack.org/#/c/196320/2/specs/devref/api-version-negotiation.rst,cm">https://review.openstack.org/#/c/196320/2/specs/devref/api-version-negotiation.rst,cm</a></span></font></div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
This is clearly backwards. Users should read release notes and be aware<br>
of what changes between versions in the API. Users need to be aware of<br>
the fact that our API is versioned, and use that to their advantage.<br></blockquote><div><br></div><div>You're conflating "user" and "operator" -- which I understand, because you are both. But not everyone is, and I'm concerned about the impact on "users who are not operators". I'd say maybe we have none of those, except then I hear from folks like Clint that they care about this sort of change and how it affects them.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
It seems to me that the goal of the version negotiation in our client<br>
has been to pretend that our API versions don't exist, from a user<br>
perspective. We need to stop doing this and force users to think about<br>
what they are doing when they interact with our API.<br></blockquote><div><br></div><div>The intent is to allow users' tooling to continue working while we evolve the REST API *and* to give users the ability to work with both old and new service installations (eg, because the user doesn't control what version of server they are using).</div><div><br></div><div>Again, that goal is based on the assumption that some users are not also operators. </div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<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></blockquote><div><br></div><div>In an environment where a user is interacting with >1 Ironic service of different versions, this default would lead to what I'll just call "odd" behavior. It ends up being your option 4 implicitly, to avoid frustration.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<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></blockquote><div><br></div><div>Do you think about what version of XMPP protocol this or that service implements? Your XMPP client certainly does, if you use a client that can talk to both hangouts and facebook and $(insert any other of a dozen variants here). You, as the user, have to tell your client "this account uses the FB variant of XMPP". I don't think users of Ironic (or more generally, users of OpenStack) want to have to think about that.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">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>
<br>
// jim<br>
<br>
[0] <a href="https://github.com/openstack/ironic/commit/1410e59228c3835cfc4f89db1ec482137a3cfa10" rel="noreferrer" target="_blank">https://github.com/openstack/ironic/commit/1410e59228c3835cfc4f89db1ec482137a3cfa10</a><br>
[1] <a href="http://specs.openstack.org/openstack/nova-specs/specs/liberty/approved/novaclient-api-microversions.html" rel="noreferrer" target="_blank">http://specs.openstack.org/openstack/nova-specs/specs/liberty/approved/novaclient-api-microversions.html</a><br>
<br>
__________________________________________________________________________<br>
OpenStack Development Mailing List (not for usage questions)<br>
Unsubscribe: <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" rel="noreferrer" target="_blank">OpenStack-dev-request@lists.openstack.org?subject:unsubscribe</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" rel="noreferrer" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
</blockquote></div></div>