Skip to main content

Stabilization Cycle

The stabilization cycle is the process by which a feature progresses from Experimental to Stable. It ensures that every capability we commit to in a Stable release has been implemented, tested, and validated before it is enabled by default and covered by our compatibility guarantees.

This document describes the stages of the cycle, the criteria a feature must meet to advance, and what happens when a feature is not ready to proceed. For an overview of the channels themselves, see Release Channels.

Overview​

A feature advances through the cycle one stage at a time. It is introduced and iterated on in Experimental, promoted to Beta once it is considered ready, validated as a release candidate, and finally stabilized when it graduates to Stable:

Introduced  ──►  Evaluated  ──►  Promoted  ──►  Validated  ──►  Stabilized
(Experimental)  (Experimental)     (Beta)         (Beta)         (Stable)

A feature only moves forward when it meets the criteria for the next stage. There is no obligation to advance a feature before it is ready.

Stages of the Cycle​

  • Introduction: The feature lands on Experimental, typically behind an explicit opt-in flag. At this stage it is available for preview but is not part of any Beta or Stable release.
  • Evaluation: The feature is exercised and refined on Experimental. Feedback is gathered, and the implementation and its configuration surface may change freely. Breaking changes are expected and permitted during this stage.
  • Promotion to Beta: Once the feature meets the stabilization criteria, it is promoted to Beta and feature-frozen. No new functionality is added after this point; only fixes and stabilization work are applied.
  • Validation: On Beta, the feature is validated as part of the next release candidate. The goal is to surface regressions and confirm that the feature behaves as intended in a near-final state.
  • Stabilization: When the release candidate graduates to Stable, the feature is enabled by default, any opt-in flag is removed, and the feature falls under our backward-compatibility guarantees.

Stabilization Criteria​

A feature must satisfy the following before it is promoted out of Experimental. These criteria protect the guarantees that apply once a feature reaches Stable.

  • Functional completeness: The feature does what it is intended to do, with no known gaps that would require breaking changes to address later.
  • Settled interface: The configuration and interface surface is stable, and we do not anticipate breaking changes to it.
  • Test coverage: The feature is covered by automated tests sufficient to guard against regressions.
  • Documentation: User-facing documentation is ready to ship alongside the feature.
  • No blocking issues: There are no unresolved issues that would prevent the feature from being relied upon in production.
  • Incorporated feedback: Feedback gathered while the feature was on Experimental has been reviewed and addressed.

Feature Flags​

While a feature is on Experimental, it may be gated behind an explicit opt-in flag. This lets users preview the feature without exposing it by default.

  • No standard mechanism: There is no standard way a feature flag is implemented or toggled. How a flag is enabled varies from feature to feature, so consult the documentation for the specific feature you want to preview.
  • Not a stable interface: Opt-in flags are part of the experimental surface. Their names, behavior, and defaults may change while the feature is being stabilized.
  • Removed at graduation: When a feature stabilizes, its opt-in flag is removed and the feature becomes enabled by default. Configuration that relied on the flag should be updated accordingly.

When a Feature Does Not Stabilize​

Not every feature completes the cycle. A feature that does not meet the criteria can be held back or reworked without affecting Stable.

  • Continued iteration: The feature remains on Experimental for further development.
  • Revision: The feature is reworked, including breaking changes, while it is still on Experimental or Beta.
  • Removal: The feature is removed entirely. Because it was never part of a Stable release, its removal does not affect the compatibility guarantees of Stable.

Relationship to Backward Compatibility​

The stabilization cycle is what makes our compatibility guarantees possible. A feature is only covered by our Backward Compatibility Policy once it has graduated to Stable. Features on Experimental and Beta are not covered and may change or be removed as described above.