Provide clear guidance on what semconv actually enforces

specification/versioning-and-stability.md

@@ -161,6 +161,58 @@ allowing the evolution of telemetry and semantic conventions, OpenTelemetry
 relies on the concept of
 [Telemetry Schemas](schemas/README.md).
 
+Semantic Conventions defines breaking changes as those that would break the
+"API" of tooling written against the telemetry it produces. That is, the portions
+of telemetry where specialized tooling (alerts, dashboards, e.g.) interact are
+expected to remain stable for that tooling after schema transformations are applied. Semantic Conventions defines the
+set of fields to which stability concerns apply as follows:
+
+- [Resource](resource/sdk.md)
+  - attribute keys provided to Create resource detectors
+- [Trace](trace/api.md)
+  - Attribute keys provided to [get a tracer](trace/api.md#get-a-tracer)
+  - The following data provided to [span](trace/api.md#span) by available APIs:
+    - The span name
+    - The span kind
+    - The attribute keys provided to the span
+      - Whether these attributes must be provided at span start time, due to
+        sampling concerns.
+  - The following data provided when [adding an event](trace/api.md#add-events)
+    - The event name
+    - The attribute keys provided for the event
+- [Metrics](metrics/api.md)
+  - Attribute keys provided to [get a meter](metrics/api.md#get-a-meter)
+  - The following arguments when constructing [an instrument](metrics/api.md#instrument):
+    - The name of the instrument
+    - The kind of instrument
+      - For `Counter` and `UpDownCounter` instruments, it is
+        acceptable to change between asynchronous and synchronous instruments.
+    - the unit of the instrument.
+  - The attribute keys provided when recording a measurement, for
+    both synchronous and asynchronous instruments.
+- [Log Records](logs/bridge-api.md#logrecord)
+  - The attribute keys provided on the LogRecord
+- [Log Events](logs/event-api.md)
+  - The following data provided to [emit event](logs/event-api.md#emit-event):
+    - The event name
+    - The event domain
+    - The components of [LogRecord](logs/bridge-api.md#logrecord) also
+      listed here.
+
+Things not listed in the above are not enforced via semantic convention and are allowed (or expected) to change. A few examples:
+
+- The values of attributes
+  - Specifically for `enums` the list of allowed values is expected to change
+    overtime.
+  - Even for `enums` that limit allowed values to semconv, some may need to
+    updated values in the future.
+- The links attached to a span
+- The recorded measurement type (float or integer) of a metric is not enforced and allowed to change.
+- The description of a metric instrument.
+- The values being recorded by an instrument.
+
+The list of telemetry fields which are covered by stability guarantees MAY be extended.
+
 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:
@@ -181,8 +233,8 @@ that are always allowed. Such changes do not need to be described (and are not
 described) by schema files. Here is the list of such changes:
 
 - Adding new attributes to the existing semantic conventions for resources,
-  spans, span events or log records. Note that adding attributes to existing metrics is
-  considered to be a breaking change.
+  spans, span events or log records.
+- Adding new attributes to existing metrics that do not create new timeseries.
 - Adding semantic conventions for new types of resources, spans, span events,
   metrics or log records.