From 210ea33f226c2a549f4db2416362940cfcd3e814 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Wed, 8 May 2024 13:56:02 +0200 Subject: [PATCH 1/5] Versioning and stability: Remove confusion around backwards compatiblity --- CHANGELOG.md | 3 +++ specification/versioning-and-stability.md | 5 +---- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d57f076c7be..586236a824b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -51,6 +51,9 @@ release. ### Common +- Versioning and stability: Clarify backwards compatibility and SemVer. + ([#4039](https://github.com/open-telemetry/opentelemetry-specification/pull/4039)) + ### Supplementary Guidelines ## v1.32.0 (2024-04-11) diff --git a/specification/versioning-and-stability.md b/specification/versioning-and-stability.md index 07a545afb5c..5e4529450d1 100644 --- a/specification/versioning-and-stability.md +++ b/specification/versioning-and-stability.md @@ -126,7 +126,6 @@ maintainers SHOULD choose the idiomatic way for their language. #### SDK Stability -Public portions of SDK packages MUST remain backwards compatible. There are two categories of public features: **plugin interfaces** and **constructors**. Examples of plugins include the SpanProcessor, Exporter, and Sampler interfaces. Examples of constructors include configuration objects, environment variables, and SDK builders. @@ -144,8 +143,6 @@ in [Telemetry Stability](telemetry-stability.md).) The goal is to ensure users c update to the latest version of OpenTelemetry, and not be held back by the plugins that they depend on. -Public portions of contrib packages (constructors, configuration, interfaces) SHOULD remain backwards compatible. - Languages which ship binary artifacts SHOULD offer [ABI compatibility](glossary.md#abi-compatibility) for contrib packages. **Exception:** Contrib packages MAY break stability when a required downstream dependency breaks stability. @@ -310,7 +307,7 @@ We invented a new tracing API, but continue to support the old one. ## Version numbers -OpenTelemetry clients follow [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html), with the following clarifications. +OpenTelemetry clients MUST follow [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html), with the following clarifications. OpenTelemetry clients have four components: API, SDK, Semantic Conventions, and Contrib. From 6cafb10b967fc3639c8c2ba99d708e39b9d00641 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Fri, 10 May 2024 11:39:40 +0200 Subject: [PATCH 2/5] Update CHANGELOG.md --- CHANGELOG.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9a3de7dec3c..04c6e03be8f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -27,6 +27,9 @@ release. ### Common +- Versioning and stability: Clarify backwards compatibility and SemVer. + ([#4039](https://github.com/open-telemetry/opentelemetry-specification/pull/4039)) + ### Supplementary Guidelines ## v1.33.0 (2024-05-09) @@ -78,9 +81,6 @@ release. ### Common -- Versioning and stability: Clarify backwards compatibility and SemVer. - ([#4039](https://github.com/open-telemetry/opentelemetry-specification/pull/4039)) - ### Supplementary Guidelines ## v1.32.0 (2024-04-11) From e5c6dfc1ac1c761ae2c98491311d891c1e024d10 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Fri, 17 May 2024 08:33:18 +0200 Subject: [PATCH 3/5] Update versioning-and-stability.md --- specification/versioning-and-stability.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/specification/versioning-and-stability.md b/specification/versioning-and-stability.md index 5e4529450d1..f8668f8240c 100644 --- a/specification/versioning-and-stability.md +++ b/specification/versioning-and-stability.md @@ -126,6 +126,7 @@ maintainers SHOULD choose the idiomatic way for their language. #### SDK Stability +Public portions of SDK packages MUST remain backwards compatible. There are two categories of public features: **plugin interfaces** and **constructors**. Examples of plugins include the SpanProcessor, Exporter, and Sampler interfaces. Examples of constructors include configuration objects, environment variables, and SDK builders. @@ -143,6 +144,7 @@ in [Telemetry Stability](telemetry-stability.md).) The goal is to ensure users c update to the latest version of OpenTelemetry, and not be held back by the plugins that they depend on. +Public portions of contrib packages (constructors, configuration, interfaces) SHOULD remain backwards compatible. Languages which ship binary artifacts SHOULD offer [ABI compatibility](glossary.md#abi-compatibility) for contrib packages. **Exception:** Contrib packages MAY break stability when a required downstream dependency breaks stability. From dd3d11fd69b3e6455424b081288bbdf1637765a5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Fri, 17 May 2024 11:00:12 +0200 Subject: [PATCH 4/5] Update CHANGELOG.md --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 04c6e03be8f..6764f3aecd5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -27,7 +27,7 @@ release. ### Common -- Versioning and stability: Clarify backwards compatibility and SemVer. +- OpenTelemetry clients MUST follow SemVer 2.0.0. ([#4039](https://github.com/open-telemetry/opentelemetry-specification/pull/4039)) ### Supplementary Guidelines From 341782c8582bf2c6933bff04d76185c14c1ab6c3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Fri, 17 May 2024 11:27:02 +0200 Subject: [PATCH 5/5] Update versioning-and-stability.md --- specification/versioning-and-stability.md | 1 + 1 file changed, 1 insertion(+) diff --git a/specification/versioning-and-stability.md b/specification/versioning-and-stability.md index f8668f8240c..fd5d8435ff7 100644 --- a/specification/versioning-and-stability.md +++ b/specification/versioning-and-stability.md @@ -145,6 +145,7 @@ update to the latest version of OpenTelemetry, and not be held back by the plugins that they depend on. Public portions of contrib packages (constructors, configuration, interfaces) SHOULD remain backwards compatible. + Languages which ship binary artifacts SHOULD offer [ABI compatibility](glossary.md#abi-compatibility) for contrib packages. **Exception:** Contrib packages MAY break stability when a required downstream dependency breaks stability.