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]

Reply via email to