Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify possibility to extend SDK interfaces #4030

Merged
merged 15 commits into from
Jun 6, 2024
Merged
Show file tree
Hide file tree
Changes from 9 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,9 @@ release.

### Supplementary Guidelines

- Clarify that it is permissible to extend SDK interfaces without requiring a major version bump
([#4030](https:/open-telemetry/opentelemetry-specification/pull/4030))

## v1.33.0 (2024-05-09)

### Context
Expand Down
38 changes: 24 additions & 14 deletions specification/versioning-and-stability.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,8 @@
* [Experimental](#experimental)
* [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)
Expand Down Expand Up @@ -104,13 +104,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.
reyang marked this conversation as resolved.
Show resolved Hide resolved
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
tigrannajaryan marked this conversation as resolved.
Show resolved Hide resolved
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
Expand All @@ -121,18 +131,18 @@ 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
Similarly, existing SDK plugin interfaces MAY be extended with new methods without incrementing the major version
pellared marked this conversation as resolved.
Show resolved Hide resolved
pellared marked this conversation as resolved.
Show resolved Hide resolved
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.
JonasKunz marked this conversation as resolved.
Show resolved Hide resolved
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 accepting the
pellared marked this conversation as resolved.
Show resolved Hide resolved
new interface in addition to the old one in every place.

There may be other ways to extend existing API/SDKs in non-breaking manner. Language
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.

Languages which ship binary artifacts SHOULD offer [ABI compatibility](glossary.md#abi-compatibility) for SDK packages.

#### Contrib Stability

Plugins, instrumentation, and other contrib packages SHOULD be kept up to date
Expand Down
Loading