From a6b85d27eec3c242a271c169dffceb6746429c1b Mon Sep 17 00:00:00 2001
From: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com>
Date: Tue, 29 Oct 2024 10:29:51 -0400
Subject: [PATCH] Add requirement to allow extending Stable APIs (#4270)

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.
---
 CHANGELOG.md                              |  3 +++
 specification/versioning-and-stability.md | 15 ++++++++++++++-
 2 files changed, 17 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 485b3ba69d6..ddf9f66a02e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -33,6 +33,9 @@ release.
 
 ### Compatibility
 
+- Add requirement to allow extending Stable APIs
+  ([#4270](https://github.com/open-telemetry/opentelemetry-specification/pull/4270))
+
 ### SDK Configuration
 
 - Clarify declarative configuration parse requirements for null vs empty.
diff --git a/specification/versioning-and-stability.md b/specification/versioning-and-stability.md
index d81831b157a..570aa11ba9e 100644
--- a/specification/versioning-and-stability.md
+++ b/specification/versioning-and-stability.md
@@ -142,10 +142,23 @@ 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 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
+  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.
+- 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.