AIP-181

Stability levels

While different organizations (both inside Google and outside) have different product life cycles, AIPs refer to the stability of an API component using the following terms.

Note: These stability levels roughly correspond to the product launch stages (alpha, beta, GA) in Google Cloud, but are not identical. GCP imposes its own additional expectations and commitments on top of what is outlined here.

Alpha

An alpha component undergoes rapid iteration with a known set of users who must be tolerant of change. The number of users should be a curated, manageable set, such that it is feasible to communicate with all of them individually.

Breaking changes must be both allowed and expected in alpha components, and users must have no expectation of stability.

Beta

A beta component must be considered complete and ready to be declared stable, subject to public testing. Beta components should be exposed to an unknown and potentially large set of users. In other words, beta components should not be behind an allowlist; instead, they should be available to the public.

Because users of beta components tend to have a lower tolerance of change, beta components should be as stable as possible; however, the beta component must be permitted to change over time. These changes should be minimal but may include backwards-incompatible changes to beta components. Backwards-incompatible changes must be made only after a reasonable deprecation period to provide users with an opportunity to migrate their code. This deprecation period must be defined at the time of being marked beta.

Beta components should be time-boxed and promoted to stable if no issues are found in the specified timeframe, which should be specified at the time of being marked beta. A reasonable time period may vary, but a good rule of thumb is 90 days.

Stable

A stable component must be fully-supported over the lifetime of the major API version. Because users expect such stability from components marked stable, there must be no breaking changes to these components, subject to the caveats described below.

Major versions

When breaking changes become necessary, the API producer should create the next major version of the API, and start a deprecation clock on the existing version.

Turn-down of any version containing stable components must have a formal process defined at the time of being marked stable. This process must specify a deprecation period for users which provides them with reasonable advance warning.

Isolated changes

On very rare occasions, it could be preferable to make a small, isolated breaking change, if this will only cause inconvenience to a small subset of users. (Creating a new major version is an inconvenience to all users.) In this case, the API producer may deprecate the component, but must continue to support the component for the normal turndown period for a stable component.

Important: Making an in-place breaking change in a stable API is considered an extreme course of action, and should be treated with equal or greater gravity as creating a new major version. For example, at Google, this requires the approval of the API Governance team.

Emergency changes

In certain exceptional cases, such as security concerns or regulatory requirements, any API component may be changed in a breaking manner regardless of its stability level, and a deprecation is not promised in these situations.