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

Add requirement to allow extending Stable APIs #4270

Merged
Changes from 1 commit
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
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
tigrannajaryan marked this conversation as resolved.
Show resolved Hide resolved
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.
lmolkova marked this conversation as resolved.
Show resolved Hide resolved
tigrannajaryan marked this conversation as resolved.
Show resolved Hide resolved
- Newly added methods are clearly marked and documented as in Development.
tigrannajaryan marked this conversation as resolved.
Show resolved Hide resolved
- 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