From 6682cd9486c1840affb1d71652cc40c58b21f147 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 18 May 2026 11:38:11 -0700 Subject: [PATCH] Clarify telemetry stability versioning requirements --- VERSIONING.md | 28 +++++++++++++++++----------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/VERSIONING.md b/VERSIONING.md index 32dbba3d0956..49b77b3ba1d3 100644 --- a/VERSIONING.md +++ b/VERSIONING.md @@ -1,22 +1,28 @@ # OpenTelemetry Java Instrumentation Versioning -## Compatibility requirements +## Compatibility and telemetry stability requirements -Artifacts in this repository follow the same compatibility requirements described in - -. +Artifacts in this repository follow the compatibility requirements described in the +[OpenTelemetry Java versioning document](https://github.com/open-telemetry/opentelemetry-java/blob/main/VERSIONING.md#compatibility-requirements) +and the OpenTelemetry specification +[versioning and stability document](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/versioning-and-stability.md). -EXCEPT for the following incompatible changes which are allowed in stable artifacts in this -repository: +For any stable artifact in this repository, public portions of the artifact must remain backward +compatible, including public Java APIs and user-facing configuration. Backward-incompatible changes +to stable artifacts are only allowed when incrementing the `MAJOR` version number, except for the +following configuration changes: -- Changes to configuration properties that contain the word `experimental` -- Changes to configuration properties under the namespace `otel.javaagent.testing` +- Changes to configuration properties that contain the word `experimental`. +- Changes to configuration properties under the namespace `otel.javaagent.testing`. This means that: -- Changes to configuration properties (other than those that contain the word `experimental` - or are under the namespace `otel.javaagent.testing`) will be considered breaking changes - (unless they only affect telemetry produced by instrumentation) +- Changes to all other configuration properties are considered breaking changes. +- Changes to telemetry produced by stable instrumentation artifacts in this repository are + considered breaking unless they are allowed by the OpenTelemetry specification + [Semantic Conventions Stability](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/versioning-and-stability.md#semantic-conventions-stability) + requirements. This repository uses those requirements to define breaking and non-breaking + telemetry changes for stable instrumentation artifacts. ## Stable vs alpha