Add text about microversions

We aren't doing anything with microversions yet, but since we just wrote
down algorithms for version discovery, let's go ahead and talk about
how microversions should work. Also, mention that it's important to
fetch information about them as part of discovery.

Change-Id: Iadd48cd53488240e33db83797a88af689b1497dc

doc/source/index.rst

@@ -17,6 +17,7 @@ Contents:
    model
    contributing
    coding
+   microversions
    future
    releasenotes
 

doc/source/microversions.rst

@@ -0,0 +1,75 @@
+=============
+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.