GitHub user Zhuoxi2000 edited a discussion: [Discussion][API] Stability labels and compatibility checks for 1.0
## 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. | Level | Java | Python | Compatibility | |---|---|---|---| | Public | `@Public` | `@public` | Stable throughout 1.x | | PublicEvolving | `@PublicEvolving` | `@public_evolving` | Stable across patch releases. Changes allowed in minor releases after deprecation | | Experimental | `@Experimental` | `@experimental` | No compatibility guarantee | | Internal | `@Internal` | `@internal` | No compatibility guarantee | For existing APIs, I'd use `PublicEvolving` as the default, with explicit labels on all public types. A smaller set of core APIs, such as `Agent`, `ChatMessage`, `Event`, and `RunnerContext`, would be marked `Public`. 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: - **YAML:** Keep previously valid YAML working. Use `docs/yaml-schema.json` to detect breaking schema changes. - **Configuration:** Preserve config keys, types, and defaults. Add support for deprecated keys so renamed options continue working. - **Built-in integrations:** Preserve resource names and YAML aliases. Constructor arguments that mirror external SDKs would follow those SDKs. ### 3. Deprecation For `Public` and `PublicEvolving` APIs, I'd propose: - Deprecate APIs before removing them, with a warning and a suggested replacement. - Keep deprecated `PublicEvolving` APIs for at least one minor release. `Public` APIs would remain compatible throughout 1.x. - Document changes and migration steps in the release notes. ### 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 1. Do these stability levels make sense? In particular, should `PublicEvolving` be the default and stay compatible across patch releases? 2. Should deprecated APIs stay for one minor release or two? 3. For built-in integrations, should compatibility also cover descriptor arguments, or just resource names and YAML aliases? Would appreciate your thoughts on this, especially @wenjin272 and @xintongsong. I'm happy to take on the implementation once we agree on the approach. GitHub link: https://github.com/apache/flink-agents/discussions/1433 ---- This is an automatically sent email for [email protected]. To unsubscribe, please send an email to: [email protected]
