Status

...

...

JIRA: None yet

...

Please keep the discussion on the mailing list rather than commenting on the wiki (wiki discussions get unwieldy fast).

...

For programmatic APIs, the Flink community has introduced different annotations to denote the stability of classes/interfaces.

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:

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:

@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().

@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.

...