20b2f1f0c0
Move the docs around a little to allow the new templated docs.o.o site link to things like the user and install guides in the expected location. Change-Id: I7f3b625c04aa6cd2a7ebe5f2ce4a398cf464b1cc Signed-off-by: Doug Hellmann <doug@doughellmann.com>
76 lines
4.0 KiB
ReStructuredText
76 lines
4.0 KiB
ReStructuredText
=============
|
|
Microversions
|
|
=============
|
|
|
|
As shade rolls out support for consuming microversions, it will do so on a
|
|
call by call basis as needed. Just like with major versions, shade should have
|
|
logic to handle each microversion for a given REST call it makes, with the
|
|
following rules in mind:
|
|
|
|
* If an activity shade performs can be done differently or more efficiently
|
|
with a new microversion, the support should be added to shade.
|
|
|
|
* shade should always attempt to use the latest microversion it is aware of
|
|
for a given call, unless a microversion removes important data.
|
|
|
|
* Microversion selection should under no circumstances be exposed to the user,
|
|
except in the case of missing feature error messages.
|
|
|
|
* If a feature is only exposed for a given microversion and cannot be simulated
|
|
for older clouds without that microversion, it is ok to add it to shade but
|
|
a clear error message should be given to the user that the given feature is
|
|
not available on their cloud. (A message such as "This cloud only supports
|
|
a maximum microversion of XXX for service YYY and this feature only exists
|
|
on clouds with microversion ZZZ. Please contact your cloud provider for
|
|
information about when this feature might be available")
|
|
|
|
* When adding a feature to shade that only exists behind a new microversion,
|
|
every effort should be made to figure out how to provide the same
|
|
functionality if at all possible, even if doing so is inefficient. If an
|
|
inefficient workaround is employed, a warning should be provided to the
|
|
user. (the user's workaround to skip the inefficient behavior would be to
|
|
stop using that shade API call)
|
|
|
|
* If shade is aware of logic for more than one microversion, it should always
|
|
attempt to use the latest version available for the service for that call.
|
|
|
|
* Objects returned from shade should always go through normalization and thus
|
|
should always conform to shade's documented data model and should never look
|
|
different to the shade user regardless of the microversion used for the REST
|
|
call.
|
|
|
|
* If a microversion adds new fields to an object, those fields should be
|
|
added to shade's data model contract for that object and the data should
|
|
either be filled in by performing additional REST calls if the data is
|
|
available that way, or the field should have a default value of None which
|
|
the user can be expected to test for when attempting to use the new value.
|
|
|
|
* If a microversion removes fields from an object that are part of shade's
|
|
existing data model contract, care should be taken to not use the new
|
|
microversion for that call unless forced to by lack of availablity of the
|
|
old microversion on the cloud in question. In the case where an old
|
|
microversion is no longer available, care must be taken to either find the
|
|
data from another source and fill it in, or to put a value of None into the
|
|
field and document for the user that on some clouds the value may not exist.
|
|
|
|
* If a microversion removes a field and the outcome is particularly intractable
|
|
and impossible to work around without fundamentally breaking shade's users,
|
|
an issue should be raised with the service team in question. Hopefully a
|
|
resolution can be found during the period while clouds still have the old
|
|
microversion.
|
|
|
|
* As new calls or objects are added to shade, it is important to check in with
|
|
the service team in question on the expected stability of the object. If
|
|
there are known changes expected in the future, even if they may be a few
|
|
years off, shade should take care to not add committments to its data model
|
|
for those fields/features. It is ok for shade to not have something.
|
|
|
|
..note::
|
|
shade does not currently have any sort of "experimental" opt-in API that
|
|
would allow a shade to expose things to a user that may not be supportable
|
|
under shade's normal compatibility contract. If a conflict arises in the
|
|
future where there is a strong desire for a feature but also a lack of
|
|
certainty about its stability over time, an experimental API may want to
|
|
be explored ... but concrete use cases should arise before such a thing
|
|
is started.
|