Repository navigation
[Discussion][API] Stability labels and compatibility checks for 1.0 #1433
Zhuoxi2000
started this conversation in
Ideas
Replies: 0 comments
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Background
API and configuration compatibility is listed as a 1.0 must-have in #1327. I'd like to pick this up and get some feedback on the approach before starting.
Right now, we don't have consistent API stability labels or a deprecation policy. We have some CI checks for Java/Python parity and YAML schemas, but nothing that checks compatibility against previous releases.
This proposal covers APIs, configuration, YAML, and built-in integrations. State compatibility is being handled separately in #1332.
Proposal
1. API stability levels
I suggest reusing Flink's Java annotations and adding equivalent Python decorators.
@Public@public@PublicEvolving@public_evolving@Experimental@experimental@Internal@internalFor existing APIs, I'd use
PublicEvolvingas the default, with explicit labels on all public types. A smaller set of core APIs, such asAgent,ChatMessage,Event, andRunnerContext, would be markedPublic.The full list can be reviewed in the labeling PR.
2. Configuration, YAML, and integrations
I'd also include the following in the compatibility contract:
docs/yaml-schema.jsonto detect breaking schema changes.3. Deprecation
For
PublicandPublicEvolvingAPIs, I'd propose:PublicEvolvingAPIs for at least one minor release.PublicAPIs would remain compatible throughout 1.x.4. Compatibility checks
We should also catch breaking changes in CI.
For Java, we can use
japicmp, and for Python,griffe. YAML, configuration, and integration checks can build on what we already have.I'd start with report-only checks against 0.4.0, then make them blocking once 1.0.0 is released. The 1.0 release would be the compatibility baseline.
I can start with the stability labels and documentation, then add the CI checks and deprecation support.
Questions
PublicEvolvingbe the default and stay compatible across patch releases?Would appreciate your thoughts on this, especially @wenjin272 and @xintongsong. I'm happy to take on the implementation once we agree on the approach.
All reactions