add api tier and compatibility guidelines for microshift

Signed-off-by: Doug Hellmann <[email protected]>

Author: dhellmann

_topic_maps/_topic_map_ms.yml

@@ -60,6 +60,10 @@ Name: API reference
 Dir: microshift_rest_api
 Distros: microshift
 Topics:
+- Name: Understanding API tiers
+  File: understanding-api-support-tiers
+- Name: API compatibility guidelines
+  File: understanding-compatibility-guidelines
 - Name: Network APIs
   Dir: network_apis
   Topics:

microshift_rest_api/modules

@@ -0,0 +1 @@
+../modules

microshift_rest_api/understanding-api-support-tiers.adoc

@@ -0,0 +1,20 @@
+:_content-type: ASSEMBLY
+[id="understanding-api-support-tiers"]
+= Understanding API tiers
+include::_attributes/common-attributes.adoc[]
+:context: understanding-api-tiers
+
+toc::[]
+
+[IMPORTANT]
+====
+This guidance does not cover layered {product-title} offerings.
+====
+
+Red Hat requests that application developers validate that any behavior they depend on is explicitly defined in the formal API documentation to prevent introducing dependencies on unspecified implementation-specific behavior or dependencies on bugs in a particular implementation of an API.  For example, new releases of an ingress router may not be compatible with older releases if an application uses an undocumented API or relies on undefined behavior.
+
+include::modules/api-support-tiers.adoc[leveloffset=+1]
+
+include::modules/api-support-tiers-mapping.adoc[leveloffset=+1]
+
+include::modules/api-support-deprecation-policy.adoc[leveloffset=+1]

microshift_rest_api/understanding-compatibility-guidelines.adoc

@@ -0,0 +1,18 @@
+:_content-type: ASSEMBLY
+[id="compatibility-guidelines"]
+= Understanding API compatibility guidelines
+include::_attributes/common-attributes.adoc[]
+:context: compatibility-guidelines
+
+toc::[]
+
+[IMPORTANT]
+====
+This guidance does not cover layered {product-title} offerings.
+====
+
+include::modules/api-compatibility-guidelines.adoc[leveloffset=+1]
+
+include::modules/api-compatibility-exceptions.adoc[leveloffset=+1]
+
+include::modules/api-compatibility-common-terminology.adoc[leveloffset=+1]

modules/api-compatibility-exceptions.adoc

@@ -34,4 +34,4 @@ Select APIs in the product expose fields with the prefix `unsupported<FieldName>
 [discrete]
 [id="API-availability-per-product-installation-topology_{context}"]
 == API availability per product installation topology
-The OpenShift distribution will continue to evolve its supported installation topology, and not all APIs in one install topology will necessarily be included in another. For example, certain topologies may restrict read/write access to particular APIs if they are in conflict with the product installation topology or not include a particular API at all if not pertinent to that topology. APIs that exist in a given topology will be supported in accordance with the compatibility tiers defined above.
+The OpenShift distribution will continue to evolve its supported installation topology, and not all APIs in one install topology will necessarily be included in another. For example, certain topologies may restrict read/write access to particular APIs if they are in conflict with the product installation topology or not include a particular API at all if not pertinent to that topology. APIs that exist in a given topology will be supported in accordance with the compatibility tiers defined above.