diff --git a/aep/general/0181/aep.md.j2 b/aep/general/0181/aep.md.j2 index 9b725395..9c5db40b 100644 --- a/aep/general/0181/aep.md.j2 +++ b/aep/general/0181/aep.md.j2 @@ -1,5 +1,76 @@ # Stability levels -**Note:** This AEP has not yet been adopted. See -[this GitHub issue](https://github.com/aep-dev/aep.dev/issues/9) for more -information. +While organizations have their own product life cycles, AEPs refer to the +_stability_ of an API component using the following terms. + +## 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 old component, but **must** continue +to support the old 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. + +### Emergency changes + +In certain exceptional cases, an API component **may** be changed in a breaking +manner regardless of its stability level, and a deprecation is not promised in +these situations. + +These cases are: + +- significant security concerns +- regulatory requirements \ No newline at end of file diff --git a/aep/general/0181/aep.yaml b/aep/general/0181/aep.yaml index 8a3de133..51ffe674 100644 --- a/aep/general/0181/aep.yaml +++ b/aep/general/0181/aep.yaml @@ -1,7 +1,7 @@ --- id: 181 -state: reviewing +state: approved slug: stability-levels -created: 2023-01-22 +created: 2024-03-17 placement: category: best-practices