From 9758cdddee20c699b620aac1d7f777ccd490f252 Mon Sep 17 00:00:00 2001
From: Jonas Kunz <Jonas.Kunz@gmx.net>
Date: Thu, 6 Jun 2024 18:49:49 +0200
Subject: [PATCH] Clarify possibility to extend SDK interfaces (#4030)

---
 CHANGELOG.md                              |  3 ++
 specification/versioning-and-stability.md | 38 +++++++++++++++--------
 2 files changed, 28 insertions(+), 13 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c91bee55cb4..5084fbaa8ad 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -49,6 +49,9 @@ release.
 
 ### Supplementary Guidelines
 
+- Clarify that it is permissible to extend SDK interfaces without requiring a major version bump
+  ([#4030](https://github.com/open-telemetry/opentelemetry-specification/pull/4030))
+
 ## v1.33.0 (2024-05-09)
 
 ### Context
diff --git a/specification/versioning-and-stability.md b/specification/versioning-and-stability.md
index c855656fe6f..d81831b157a 100644
--- a/specification/versioning-and-stability.md
+++ b/specification/versioning-and-stability.md
@@ -12,8 +12,8 @@
   * [Development](#development)
   * [Stable](#stable)
     + [API Stability](#api-stability)
-      - [Extending Existing API Calls](#extending-existing-api-calls)
     + [SDK Stability](#sdk-stability)
+    + [Extending API/SDK abstractions](#extending-apisdk-abstractions)
     + [Contrib Stability](#contrib-stability)
     + [Semantic Conventions Stability](#semantic-conventions-stability)
     + [Telemetry Stability](#telemetry-stability)
@@ -108,13 +108,23 @@ All existing API calls MUST continue to compile and function against all future
 
 Languages which ship binary artifacts SHOULD offer [ABI compatibility](glossary.md#abi-compatibility) for API packages.
 
-##### Extending Existing API Calls
+#### SDK Stability
+
+Public portions of SDK packages MUST remain backwards compatible.
+There are two categories of public features: **plugin interfaces** and **constructors**.
+A plugin interface is an extension point provided by the SDK which is intended to be implemented by end users in order to customize SDK behaviors.
+Examples of plugins interfaces include SpanProcessor, Exporter, and Sampler.
+Examples of constructors include configuration objects, environment variables, and SDK builders.
 
-An existing API call MAY be extended without incrementing the major version
+Languages which ship binary artifacts SHOULD offer [ABI compatibility](glossary.md#abi-compatibility) for SDK packages.
+
+#### Extending API/SDK abstractions
+
+An existing API/SDK call MAY be extended without incrementing the major version
 number if the particular language allows to do it in a backward-compatible
 manner.
 
-To add a new parameter to an existing API call depending on the language several
+To add a new parameter to an existing API/SDK call depending on the language several
 approaches are possible:
 
 - Add a new optional parameter to existing methods. This may not be the right
@@ -125,17 +135,19 @@ approaches are possible:
   include the new parameter. This is likely the preferred approach for languages
   where method overloads are possible.
 
-There may be other ways to extend existing APIs in non-breaking manner. Language
-maintainers SHOULD choose the idiomatic way for their language.
-
-#### SDK Stability
+Similarly, existing SDK plugin interfaces MAY be extended with new methods without incrementing the major version
+number if the particular language allows to do it in a backward-compatible
+manner (e.g. by providing default implementations). Hereby, backwards-compatible means that end user's code that implements
+the plugin interfaces MUST continue to be possible to use with newer versions of the SDK without making changes to the end user's code.
+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.
 
-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.
+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.
+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.
 
-Languages which ship binary artifacts SHOULD offer [ABI compatibility](glossary.md#abi-compatibility) for SDK packages.
+There may be other ways to extend existing API/SDKs in non-breaking manner. Language
+maintainers SHOULD choose the idiomatic way for their language.
 
 #### Contrib Stability