Define semantic conventions and instrumentation stability

Summary of changes:

- Explain that schemas define what changes are allowed.
- Clarify additive changes are an exception and are always allowed.
- Prohibit instrumentation changes until July 1, 2022 to allow recipients
  (backends/vendors) to start understanding Schema URLs/Schema Files.

CHANGELOG.md

@@ -34,6 +34,9 @@ release.
 
 ### Telemetry Schemas
 
+- Define semantic conventions and instrumentation stability.
+  ([#2180](https://github.com/open-telemetry/opentelemetry-specification/pull/2180))
+
 ## v1.8.0 (2021-11-12)
 
 ### Context

specification/versioning-and-stability.md

@@ -7,28 +7,28 @@
 
 <!-- toc -->
 
-- [Design goals](#design-goals)
-- [Signal lifecycle](#signal-lifecycle)
+* [Design goals](#design-goals)
+* [Signal lifecycle](#signal-lifecycle)
   * [Experimental](#experimental)
   * [Stable](#stable)
-    + [API Stability](#api-stability)
-      - [Extending Existing API Calls](#extending-existing-api-calls)
-    + [SDK Stability](#sdk-stability)
-    + [Contrib Stability](#contrib-stability)
-    + [NOT DEFINED: Telemetry Stability](#not-defined-telemetry-stability)
-    + [NOT DEFINED: Semantic Conventions Stability](#not-defined-semantic-conventions-stability)
+    * [API Stability](#api-stability)
+      * [Extending Existing API Calls](#extending-existing-api-calls)
+    * [SDK Stability](#sdk-stability)
+    * [Contrib Stability](#contrib-stability)
+    * [Semantic Conventions Stability](#semantic-conventions-stability)
+    * [Telemetry Stability](#telemetry-stability)
   * [Deprecated](#deprecated)
   * [Removed](#removed)
   * [A note on replacing signals](#a-note-on-replacing-signals)
-- [Version numbers](#version-numbers)
+* [Version numbers](#version-numbers)
   * [Major version bump](#major-version-bump)
   * [Minor version bump](#minor-version-bump)
   * [Patch version bump](#patch-version-bump)
-- [Long Term Support](#long-term-support)
+* [Long Term Support](#long-term-support)
   * [API support](#api-support)
   * [SDK Support](#sdk-support)
   * [Contrib Support](#contrib-support)
-- [OpenTelemetry GA](#opentelemetry-ga)
+* [OpenTelemetry GA](#opentelemetry-ga)
 
 <!-- tocstop -->
 
@@ -149,20 +149,70 @@ For example, a database integration may break stability if the required database
 However, it is strongly RECOMMENDED that older contrib packages remain stable.
 A new, incompatible version of an integration SHOULD be released as a separate contrib package, rather than break the existing contrib package.
 
-#### NOT DEFINED: Telemetry Stability
-
-**Telemetry stability guarantees are TBD.**
-
-Changes to telemetry produced by OpenTelemetry instrumentation SHOULD avoid breaking analysis tools, such as dashboards and alerts.
-However, it is not clear at this time what type of instrumentation changes (for example, adding additional spans and attributes) would actually cause a breaking change.
-
-#### NOT DEFINED: Semantic Conventions Stability
-
-Telemetry stability, including semantic conventions, is not currently defined. The following practices are recommended.
-
-Semantic Conventions SHOULD NOT be removed once they are added.
-New conventions MAY be added to replace usage of older conventions, but the older conventions SHOULD NOT be removed.
-Older conventions SHOULD be marked as deprecated when they are replaced by newer conventions.
+#### Semantic Conventions Stability
+
+Changes to telemetry produced by OpenTelemetry instrumentation SHOULD avoid
+breaking analysis tools, such as dashboards and alerts. To achieve this, while
+allowing the evolution of telemetry and semantic conventions, OpenTelemetry
+relies on the concept of
+[schemas](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/schemas/overview.md).
+
+Changes to semantic conventions in this specification are allowed, provided that
+the changes can be described by schema files. The following changes can be
+currently described and are allowed:
+
+- Renaming of attributes.
+- Renaming of metrics
+- Renaming of span events.
+
+All such changes MUST be described in the OpenTelemetry
+[Schema File Format](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/schemas/file_format_v1.0.0.md)
+and published
+[here](https://github.com/open-telemetry/opentelemetry-specification/tree/main/schemas).
+For details see [how OpenTelemetry Schemas are
+published](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/schemas/overview.md#opentelemetry-schema).
+
+In addition to the 3 types of changes described above, adding conventions for
+new attributes, resources, metrics, spans, span events or log records is always
+allowed. Such changes do not need to be described (and are not described) by
+schema files.
+
+Any other changes to semantic conventions are currently prohibited. Other types
+of changes MAY be introduced in the future versions of this specification. This
+is only allowed if OpenTelemetry introduces a new schema file format that is
+capable of describing such changes.
+
+#### Telemetry Stability
+
+This section defines stability requirements for telemetry produced by
+instrumentations, such as OpenTelemetry SDKs.
+
+Instrumentations, which include the Schema URL in the produced telemetry are
+allowed to change the produced telemetry after July 1, 2022 if both of the
+following conditions are fulfilled:
+
+- The change is part of OpenTelemetry semantic conventions and are in a released
+  version of the specification,
+- The change has a corresponding
+  [published](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/schemas/overview.md#opentelemetry-schema)
+  OpenTelemetry Schema File that describes the change.
+
+If the change was introduced in the specification before July 1, 2022 the
+instrumentations must wait until July 1, 2022 before they can adopt the change
+and begin producing the changed telemetry.
+
+Instrumentations, which do not include the Schema URL in the produced telemetry
+are prohibited from changing any produced telemetry that is described by
+OpenTelemetry semantic conventions.
+
+Note that adding of new attributes, metrics, spans, span events or log records
+are considered additive, non-breaking changes and are always allowed, whether
+the instrumentation includes the Schema URL in the produced telemetry or no.
+
+OpenTelemetry SDKs SHOULD NOT produce telemetry that is not described by
+OpenTelemetry semantic conventions. If, however, this rule is broken the SDKs
+MUST NOT change such telemetry, regardless of whether they include the Schema
+URL in the produced telemetry or no.
 
 ### Deprecated