Open Stack

After the long and contentious discussion about migration options, 
Rodrigo and I have reached agreement about how we should handle them 
that works for both of us, and I will share it here before Rodrigo 
updates the spec. Discussion about the proposal can continue here on the 
ML or in the spec, but the final decision will be made through the spec 
approval process.

===============

The main assumptions that drive this conclusion are:
* The API design must not violate our agreed-upon versioning 
(microversions) scheme as the API evolves over time.
* Actions requested by a client must result in behavior that is the same 
across server versions. It's not okay to get "bonus" behaviors due to a 
server upgrade if the client doesn't ask for them.

For the REST API, we propose that all the options are mandatory 
booleans. There will be no defaults at the API level. Values of false 
for options will always be compatible with the fallback/universal 
migration strategy. The options will be:
* writable
* preserve-metadata
* non-disruptive
* preserve-snapshots

Omitting any one of these is an error. This ensures safety by making 
clients send a value of true or false ensuring there are no surprise 
downsides to performing a migration.

For future migration options, they will be added with a new microversion 
and they will also be required options (in the new microversion). Newer 
server versions will provide backwards compatibility by defaulting 
options to false when clients invoke older microversions where that 
option didn't exist.

For the pythonclient, we propose that options are mandatory on the CLI. 
Again this provides safety by avoiding situations where users who don't 
read the docs are surprised by the behavior they get. This ensures that 
CLI scripts that invoke migrations will never break as long as the 
client version remains the same, and that they will get consistent 
behavior across all servers versions that support that client.

Updating to newer python clients may introduce new required parameters 
though, which can break old scripts, so this will have the effect of 
tying CLI scripts to specific client versions.

The client will provide backwards compatibility with older servers by 
only allowing requests to be sent if the user specifies a value of false 
for any option that doesn't exist on the server. This ensures that users 
always get exactly what they ask for, or an error if what they asked for 
can't be provided. It again avoids surprise behavior.

For the UI, options will always be specified as checkboxes, which will 
default to checked (true).

===============

This proposal was arrived at after thinking through a long list of 
hypothetical use cases involving newer and older clients and servers as 
well as use of apps which import the client, usage of the client's CLI 
interface, usage of the UI, and direct calls to the REST API without 
using the client.

Also we specifically considered hypothetical future migration options 
and how they would affect the API. I'm confident that this is as "safe" 
as the API and CLIs can be, and the only downside I can see to this 
approach is that it's more verbose than alternatives that include 
implicit defaults.

-Ben Swartzlander