Track feature gate lifecycle: stage advancement and legacy-ID removal

Purpose

This is the living tracker for the lifecycle of every Jaeger-registered feature gate: when each gate should advance a stage (Alpha → Beta → Stable) and, for renamed gates, when the deprecated legacy ID should be removed. It exists because gate transitions are easy to forget — the release checklist in RELEASE.md points here so they are reviewed before each release. The durable rules and conventions for feature gates (naming, FromVersion/ToVersion semantics, the rename/deprecation cycle) live in CONTRIBUTING.md, not here.

Gate inventory and recommended transitions

Latest released version: v2.20.0 (2026-07-19). Next release: v2.21.0. Introduced is the release the gate ID was first registered (its FromVersion, which never changes); Stage since is the release the gate entered its current stage. ✅ marks a transition already delivered on main (awaiting the next release).

Gate ID	Kind	Introduced	Stage	Stage since	Recommended next transition
jaeger.clickhouse	current	v2.21.0	Stable ✅ (#9058)	v2.21.0	Remove in v2.23.0 (ToVersion)
storage.clickhouse	legacy alias	v2.18.0	Stable ✅ (#9058)	v2.21.0	Remove in v2.23.0 (ToVersion)
jaeger.es.nativeTraceSummaries	current	v2.20.0	Beta	v2.20.0	→ Stable in v2.22.0 (set ToVersion)
jaeger.es.omitParentSpanIDReference	current	v2.20.0	Alpha	v2.20.0	→ Beta in v2.22.0, once proven in the field
jaeger.es.config.rejectLegacyRotationFlags	current	v2.21.0	Beta	v2.21.0	→ Stable in v2.24.0 (after legacy alias removed)
es.config.rejectLegacyRotationFlags	legacy alias	v2.9.0	Beta	v2.20.0	Remove in v2.23.0
jaeger.es.index.relativeTimeIndexDeletion	current	v2.21.0	Beta	v2.21.0	→ Stable in v2.24.0 (after legacy alias removed)
es.index.relativeTimeIndexDeletion	legacy alias	v2.5.0	Beta	v2.20.0	Remove in v2.23.0

Notes

• ClickHouse was promoted Alpha → Stable directly (delivered in #9058): the gate was a mandatory experimental opt-in (NewFactory hard-failed when disabled), not a rollout gate. ClickHouse has been available since v2.18.0 and no longer needs a gate to enable; the backend is selected through configuration, which is itself opt-in. Both gate IDs stay registered as Stable only so existing --feature-gates values keep working until removal in v2.23.0.
• The two jaeger.es.* renamed Beta gates cannot go Stable until their legacy aliases are removed (RenamedGate supports only Alpha/Beta), hence the two-step sequence: drop the legacy alias in v2.23.0, then promote the replacement to Stable in v2.24.0.
• These target versions are recommendations, not commitments; revisit each before the corresponding release.

Release-time playbook (for an AI agent)

Step 4 of the backend release checklist in RELEASE.md points an agent here while preparing release vX.Y.Z. This issue is the standing authorization for the transitions in the table above, so a PR that implements one does not need a separate issue. Steps:

1. Trust the code, not this table. The table is hand-maintained and may lag reality. Confirm each gate's current stage, FromVersion, and ToVersion from the registrations: git grep -n 'GlobalRegistry().MustRegister' -- '*.go' ':!*.pb.go' ':!*_test.go'.
2. Find what's due. A transition is due when its Recommended next transition targets vX.Y.Z and is not already ✅. Do not advance a gate early just because you are here, and do not invent transitions that are not listed.
3. Make the change following the conventions in CONTRIBUTING.md: bump the Stage (setting ToVersion on the move to Stable/Deprecated), remove a legacy alias, or delete a gate ID that has reached its ToVersion — deleting any now-dead code paths and RenamedGate wiring along with it. Removing a Stable gate at its ToVersion deletes only the toggle, not the feature (which stays permanently enabled). Each of these is a user-facing breaking change: add a CHANGELOG entry. Remember a renamed gate cannot reach Stable until its legacy alias is removed first.
4. Update this issue in the same PR: mark delivered transitions ✅ with the PR link, advance Stage since, drop rows for gate IDs that were removed, and refresh the "Latest released version / Next release" line above the table.
5. Surface divergence. If reality does not match the table (a gate at an unexpected stage, a missed soak period, a removed gate still referenced), call it out in the PR description rather than silently reconciling.