...
For programmatic APIs, the Flink community has introduced different annotations to denote the stability of classes/interfaces.
Annotation | Meaning |
| API is internal & stable but might change across releases (major, minor, patch). This API can change between patch versions. |
| API can change across releases (major, minor, patch). This API can change between patch versions. |
| API is intended for public use but it can change across releases (major, minor). Changing this API requires a new minor version. |
| API is intended for public use and it can only change across major releases. Changing this API requires a new major version. |
What we guarantee in terms of stability is that a program written against a public API will compile w/o errors when upgrading Flink (API backwards compatibility). There is no official guarantee that a program compiled against an earlier version can be executed on a newer Flink cluster (no ABI backwards compatibility). But eventually we should try provide this guarantee.
...
This would lead to the following guarantees:
Annotation | Meaning |
| API is internal and might change across releases (major, minor, patch). This API can change between any two versions. |
| API can change across releases (major, minor, patch). This API can change between any two versions. |
| API is intended for public use but it can change across releases (major, minor) → stable across 1.1.Z. A new minor release is required to change this API. |
| API is intended for public use and it can only change across major releases → stable across 1.Y.Z. A new major release is required for this API to change. |
I would suggest that we document these guarantees prominently under /docs/dev/api_stability
.
...
It is possible to add methods with weaker stability guarantees to a class/interface with stricter guarantees if we can also provide a default implementation. Differently said, features with weaker stability guarantees mustn’t entail any actions from the user unless she wants to use this feature (opt-in). For example, the following extension is valid:
Code Block | ||||
---|---|---|---|---|
| ||||
@Public
interface Foobar {
@Public
int foo();
@Experimental
default ExperimentalResult bar() {
return ExperimentalResult.notSupported();
}
} |
Whereas the following example is not valid because it requires the user to implement the method bar().
Code Block | ||||
---|---|---|---|---|
| ||||
@Public
interface Foobar {
@Public
int foo();
@Experimental
ExperimentalResult bar();
} |
Moreover, it is possible to remove methods with weaker stability guarantees from a class with stricter guarantees.
...