Open Stack

On 06/05/2015 11:03 AM, David Kranz wrote:
> On 06/05/2015 07:32 AM, Sean Dague wrote:
>> One of the things we realized at the summit was that we'd been working
>> through a better future for the Nova API for the past 5 cycles, gotten
>> somewhere quite useful, but had really done a poor job on communicating
>> what was going on and why, and where things are headed next.
>>
>> I've written a bunch of English to explain it (which should be on the
>> planet shortly as well) -
>> https://dague.net/2015/06/05/the-nova-api-in-kilo-and-beyond-2/ (with
>> lots of help from Ed Leaf, John Garbutt, and Matt Gillard on content and
>> copy editing).
>>
>> Yes, this is one of those terrible mailing list posts that points people
>> to read a thing not on the list (I appologize). But at 2700 words, I
>> think you'll find it more comfortable to read not in email.
>>
>> Discussion is welcome here for any comments folks have. Some details
>> were trimmed for the sake of it not being a 6000 word essay, and to make
>> it accessible to people that don't have a ton of Nova internals
>> knowledge. We'll do our best to field questions, all of which will be
>> integrated into the eventual dev ref version of this.
>>
>> Thanks for your time,
>>
>>     -Sean
>>
> Thanks, Sean. Great writeup. There are two issues I think might need
> more clarification/amplification:
> 
> 1. Does the microversion methodology, and the motivation for true
> interoperability, imply that there needs to be a new version for every
> bug fix that could be detected by users of an api? There was back and
> forth about that in the review about the ip6 server list filter bug you
> referenced. If so, this is a pretty strong constraint that will need
> more guidance for reviewers about which kinds of changes need new
> versions and which don't.

Correct, Alex is working on this recommendation for the API WG. But,
yes, user visible changes should be reflected in a version bump, so they
user knows that feature A is supported at version X.Y.

> 2. What is the policy for making incompatible changes, now that
> versioning "allows" such changes to be made? If some one doesn't like
> the name of one of the keys in a returned dict, and submits a change
> with new microversion, how should that be evaluated? IIRC, this was an
> issue that inspired some dislike about the original v3 work.

That's a per project call. And it's about the tradeoffs in cost vs.
benefit. Key renames are probably not worth it unless they are really
confusing.

For instance, the Nova team is currently considering (though in no ways
has decided) renaming the "evacuate" action to "resurrect" because *so*
much confusion has been created by the name evacuate (and so many
incorrectly designed applications assuming it would do things it
doesn't) that the pain of making people change might be worth it. Might.
We'll see how it plays out.

	-Sean

-- 
Sean Dague
http://dague.net