View on GitHub| Stability levels | |
|---|---|
| Number | 181 |
| Permalink | google.aip.dev/181 |
| State | Approved |
| Created | 2019-02-18 |
| Updated | 2019-02-18 |
AIP-181
Stability levels
While different organizations (both inside Google and outside) have differentproduct life cycles, AIPs refer to thestability of an API component usingthe following terms.
Note: These stability levels roughly correspond to the product launchstages (alpha, beta, GA) in Google Cloud, but are not identical. GCP imposesits own additional expectations and commitments on top of what is outlinedhere.
Alpha
Analpha component undergoes rapid iteration with a known set of users whomust be tolerant of change. The number of usersshould be acurated, manageable set, such that it is feasible to communicate with allof them individually.
Breaking changesmust be both allowed and expected in alpha components, andusersmust have no expectation of stability.
Beta
Abeta componentmust be considered complete and ready to be declaredstable, subject to public testing. Beta componentsshould be exposed to anunknown and potentially large set of users. In other words, beta componentsshould not be behind an allowlist; instead, theyshould be available tothe public.
Because users of beta components tend to have a lower tolerance of change, betacomponentsshould be as stable as possible; however, the beta componentmust be permitted to change over time. These changesshould be minimalbutmay include backwards-incompatible changes to beta components.Backwards-incompatible changesmust be made only after a reasonabledeprecation period to provide users with an opportunity to migrate their code.This deprecation periodmust be defined at the time of being marked beta.
Beta componentsshould be time-boxed and promoted to stable if no issuesare found in the specified timeframe, whichshould be specified at the timeof being marked beta. A reasonable time periodmay vary, but a good rule ofthumb is 90 days.
Stable
Astable componentmust be fully-supported over the lifetime of the majorAPI version. Because users expect such stability from components marked stable,theremust be no breaking changes to these components, subject to thecaveats described below.
Major versions
When breaking changes become necessary, the API producershould create thenext major version of the API, and start a deprecation clock on the existingversion.
Turn-down of any version containing stable componentsmust have a formalprocess defined at the time of being marked stable. This processmustspecify a deprecation period for users which provides them with reasonableadvance warning.
Isolated changes
On very rare occasions, it could be preferable to make a small, isolatedbreaking change, if this will only cause inconvenience to a small subset ofusers. (Creating a new major version is an inconvenience to all users.) In thiscase, the API producermay deprecate the component, butmust continueto support the component for the normal turndown period for a stable component.
Important: Making an in-place breaking change in a stable API is consideredan extreme course of action, and should be treated with equal or greatergravity as creating a new major version. For example, at Google, this requiresthe approval of the API Governance team.
Emergency changes
In certain exceptional cases, such as security concerns or regulatoryrequirements, any API componentmay be changed in a breaking mannerregardless of its stability level, and a deprecation is not promised in thesesituations.