Unleash / unleash / 21867475502

push

github

feat: explicit API stability (#11211)

## About the changes

This PR introduces automated API stability tracking using explicit
release milestones instead of a manual `beta: true` flag. Endpoints now
declare a release object (beta, stable, or both), and the current
Unleash version drives stability (alpha, beta, stable). This makes
stability self‑expiring and prevents endpoints from staying stuck in
beta because someone forgot to flip a boolean.

## Key benefits

- Self‑expiring milestones: version milestones automatically roll
endpoints forward; no manual cleanup
- More reliable than booleans: avoids “forgot to flip beta off” drift
- Explicit lifecycle: alpha/beta/stable windows are documented at the
endpoint definition **(open conversation about naming)**
- Selective disclosure: alpha endpoints are hidden from public docs but
remain functional for testing

Full details: See the ADR at
contributing/ADRs/back-end/api-version-tracking.md (link:
https://github.com/Unleash/unleash/blob/feat/opinionated-api-stability/contributing/ADRs/back-end/api-version-tracking.md)

## Developer guidance (assuming current version is 7.4.0)

- release is required for new endpoints, currently not enforced, but
once backfilled existing endpoints, it will be.
- release: `{ beta: 'x.y.z' }` → alpha until beta, then beta thereafter.
- release: `{ stable: 'x.y.z' }` → alpha until stable, then stable
thereafter.
- release: `{ beta: 'x.y.z', stable: 'a.b.c' }` → alpha → beta → stable
(beta must be before stable).
- release: `{ alpha: true }` → explicitly remain alpha.

**Examples:**
Assuming current is 7.4.0
- Beta today: `release: { beta: '7.1.0' }`.
- Beta now, stable later: `release: { beta: '7.3.0', stable: '7.6.0' }`.
- Alpha now, then stable: `release: { stable: '7.6.0' }`.
- Alpha now, then beta, then stable: `release: { beta: '7.6.0', stable:
'7.7.0' }`.
- Alpha until changed: `release: { alpha: true }`.

## Discussion points

- Removed beta flag: replaced by release mil... (continued)

1715 of 1930 branches covered (88.86%)

51 of 56 new or added lines in 3 files covered. (91.07%)

14367 of 16672 relevant lines covered (86.17%)

912.31 hits per line