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.

Sign up for GitHub

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

Add requirement to allow extending Stable APIs #4270

Merged
merged 7 commits into from
Oct 29, 2024
Merged

Add requirement to allow extending Stable APIs #4270

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
b04a14a
Add requirement to allow extending Stable APIs
tigrannajaryan Oct 22, 2024
95e0c91
Address PR comments
tigrannajaryan Oct 23, 2024
7bfd87b
Address PR comments
tigrannajaryan Oct 24, 2024
2d6441e
Address PR comments
tigrannajaryan Oct 24, 2024
5d7d103
Address PR comments
tigrannajaryan Oct 25, 2024
ff7e129
Add changelog entry
tigrannajaryan Oct 25, 2024
c352b47
Capitalize MAY
tigrannajaryan Oct 28, 2024
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
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
15 changes: 14 additions & 1 deletion specification/versioning-and-stability.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
tigrannajaryan marked this conversation as resolved.
Show resolved Hide resolved

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
Loading