From b04a14a08980699189a9b046bf63497d76b62f51 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Tue, 22 Oct 2024 17:07:24 -0400 Subject: [PATCH 1/7] Add requirement to allow extending Stable APIs Resolves https://github.com/open-telemetry/opentelemetry-specification/issues/4257 This issue has been discussed in spec SIG meeting on 22 Oct 2024 and decision was made that we want this to be a requirement for language implementations. This is a new requirement for implementations, which we believe becomes more and more important now that we have Stable signals that we would like to continue evolving. --- specification/versioning-and-stability.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/specification/versioning-and-stability.md b/specification/versioning-and-stability.md index d81831b157a..3492970b781 100644 --- a/specification/versioning-and-stability.md +++ b/specification/versioning-and-stability.md @@ -142,10 +142,22 @@ the plugin interfaces MUST continue to be possible to use with newer versions of For languages that commonly share code via binary artifacts, e.g. Java, backwards-compatible means that end user's code that implements plugin interfaces MUST continue to be possible to use with newer minor or patch versions without recompiling the end user's code. If this backwards compatible addition of methods to interfaces is not possible for a language, -the language maintainers MAY still implement the addition using backwards-compatible workarounds without incrementing the major version. +the language maintainers SHOULD still implement the addition using backwards-compatible +workarounds without incrementing the major version. For example, a possible workaround might be to add a new interface instead of extending the existing one and accept the new interface in addition to the old one in every place. +Additionally, a Stable signal's API/SDK may be extended by adding new calls to existing +Stable APIs. Language implementations SHOULD have a mechanism to do so, such that: + +- Adding a new method in Development maturity level is possible and is not a breaking + change for users that do not use the new method. It is acceptable that to use the + new method the user must opt-in explicitly, provided that such opt-in operation is easy. +- Newly added methods are clearly marked and documented as in Development. +- Removing (or deprecating) a method that was in Development maturity level but did + not graduate to Stable level is not a breaking change for users that never used the + method. + There may be other ways to extend existing API/SDKs in non-breaking manner. Language maintainers SHOULD choose the idiomatic way for their language. From 95e0c915aa56ec5798d1753d6c34bcac52ab338a Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Wed, 23 Oct 2024 10:07:06 -0400 Subject: [PATCH 2/7] Address PR comments --- specification/versioning-and-stability.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specification/versioning-and-stability.md b/specification/versioning-and-stability.md index 3492970b781..bf3fbcfd3cd 100644 --- a/specification/versioning-and-stability.md +++ b/specification/versioning-and-stability.md @@ -152,7 +152,8 @@ Stable APIs. Language implementations SHOULD have a mechanism to do so, such tha - Adding a new method in Development maturity level is possible and is not a breaking change for users that do not use the new method. It is acceptable that to use the - new method the user must opt-in explicitly, provided that such opt-in operation is easy. + new method the user must opt-in explicitly, provided that such opt-in operation is + easy and documented. - Newly added methods are clearly marked and documented as in Development. - Removing (or deprecating) a method that was in Development maturity level but did not graduate to Stable level is not a breaking change for users that never used the From 7bfd87bc43bf03e7a95e20591fcbad90f8300cdf Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Thu, 24 Oct 2024 10:08:54 -0400 Subject: [PATCH 3/7] Address PR comments --- specification/versioning-and-stability.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/specification/versioning-and-stability.md b/specification/versioning-and-stability.md index bf3fbcfd3cd..6f5f98909e2 100644 --- a/specification/versioning-and-stability.md +++ b/specification/versioning-and-stability.md @@ -151,9 +151,10 @@ Additionally, a Stable signal's API/SDK may be extended by adding new calls to e Stable APIs. Language implementations SHOULD have a mechanism to do so, such that: - Adding a new method in Development maturity level is possible and is not a breaking - change for users that do not use the new method. It is acceptable that to use the - new method the user must opt-in explicitly, provided that such opt-in operation is - easy and documented. + change for users that do not use the new method. +- New in Development methods SHOULD require opt-in, so that the user is made aware of + the risk associated with using the development API. It should be documented that + the newly added methods are in Development and are subject to breaking changes. - Newly added methods are clearly marked and documented as in Development. - Removing (or deprecating) a method that was in Development maturity level but did not graduate to Stable level is not a breaking change for users that never used the From 2d6441e561a90ccfb171ff320187fb1471aad74d Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Thu, 24 Oct 2024 10:11:21 -0400 Subject: [PATCH 4/7] Address PR comments --- specification/versioning-and-stability.md | 1 - 1 file changed, 1 deletion(-) diff --git a/specification/versioning-and-stability.md b/specification/versioning-and-stability.md index 6f5f98909e2..68f58f5b5b4 100644 --- a/specification/versioning-and-stability.md +++ b/specification/versioning-and-stability.md @@ -155,7 +155,6 @@ Stable APIs. Language implementations SHOULD have a mechanism to do so, such tha - New in Development methods SHOULD require opt-in, so that the user is made aware of the risk associated with using the development API. It should be documented that the newly added methods are in Development and are subject to breaking changes. -- Newly added methods are clearly marked and documented as in Development. - Removing (or deprecating) a method that was in Development maturity level but did not graduate to Stable level is not a breaking change for users that never used the method. From 5d7d103daf3ad645ae7628c6542f16739790f6ee Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Thu, 24 Oct 2024 22:40:32 -0400 Subject: [PATCH 5/7] Address PR comments --- specification/versioning-and-stability.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/versioning-and-stability.md b/specification/versioning-and-stability.md index 68f58f5b5b4..3b17a99be3f 100644 --- a/specification/versioning-and-stability.md +++ b/specification/versioning-and-stability.md @@ -147,7 +147,7 @@ workarounds without incrementing the major version. For example, a possible workaround might be to add a new interface instead of extending the existing one and accept the new interface in addition to the old one in every place. -Additionally, a Stable signal's API/SDK may be extended by adding new calls to existing +Additionally, a Stable signal's API/SDK may be extended by adding new methods to existing Stable APIs. Language implementations SHOULD have a mechanism to do so, such that: - Adding a new method in Development maturity level is possible and is not a breaking From ff7e129f2e6551ee438208f0d49a61f088fe16f1 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Thu, 24 Oct 2024 22:42:57 -0400 Subject: [PATCH 6/7] Add changelog entry --- CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index ba4d9e6a111..fc456ab8a49 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -28,6 +28,9 @@ release. ### Compatibility +- Add requirement to allow extending Stable APIs + ([#4270](https://github.com/open-telemetry/opentelemetry-specification/pull/4270)) + ### SDK Configuration ### Common From c352b473aa92f0312d8f9dbe08ab5ad772cf8195 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Mon, 28 Oct 2024 10:52:02 -0400 Subject: [PATCH 7/7] Capitalize MAY --- specification/versioning-and-stability.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/versioning-and-stability.md b/specification/versioning-and-stability.md index 3b17a99be3f..570aa11ba9e 100644 --- a/specification/versioning-and-stability.md +++ b/specification/versioning-and-stability.md @@ -147,7 +147,7 @@ workarounds without incrementing the major version. For example, a possible workaround might be to add a new interface instead of extending the existing one and accept the new interface in addition to the old one in every place. -Additionally, a Stable signal's API/SDK may be extended by adding new methods to existing +Additionally, a Stable signal's API/SDK MAY be extended by adding new methods to existing Stable APIs. Language implementations SHOULD have a mechanism to do so, such that: - Adding a new method in Development maturity level is possible and is not a breaking