Skip to content

Commit

Permalink
Add requirement to allow extending Stable APIs
Browse files Browse the repository at this point in the history
Resolves open-telemetry#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.
  • Loading branch information
tigrannajaryan committed Oct 22, 2024
1 parent 4926dfb commit b04a14a
Showing 1 changed file with 13 additions and 1 deletion.
14 changes: 13 additions & 1 deletion specification/versioning-and-stability.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down

0 comments on commit b04a14a

Please sign in to comment.