From eeb84afe3649275a44024a30d9a9fc9d56893a96 Mon Sep 17 00:00:00 2001 From: Yusuke Tsutsumi Date: Sun, 17 Mar 2024 22:16:06 -0700 Subject: [PATCH 1/2] feat(181): Import AEP-181 from AIP-181 notable differences are: - removed all references to Google. - slight change of formatting in "emergency changes", to clearly outline scenarios where such change are acceptable. --- aep/general/0181/aep.md.j2 | 77 ++++++++++++++++++++++++++++++++++++-- aep/general/0181/aep.yaml | 4 +- 2 files changed, 76 insertions(+), 5 deletions(-) diff --git a/aep/general/0181/aep.md.j2 b/aep/general/0181/aep.md.j2 index 9b725395..a3536774 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 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. + +### 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 reuqirements \ 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 From f782bd62e14763a16e3442770c84c528bc600255 Mon Sep 17 00:00:00 2001 From: Yusuke Tsutsumi Date: Tue, 19 Mar 2024 23:32:56 -0700 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Alex Stephen <1325798+rambleraptor@users.noreply.github.com> --- aep/general/0181/aep.md.j2 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/aep/general/0181/aep.md.j2 b/aep/general/0181/aep.md.j2 index a3536774..9c5db40b 100644 --- a/aep/general/0181/aep.md.j2 +++ b/aep/general/0181/aep.md.j2 @@ -57,8 +57,8 @@ advance warning. 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. +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 @@ -73,4 +73,4 @@ these situations. These cases are: - significant security concerns -- regulatory reuqirements \ No newline at end of file +- regulatory requirements \ No newline at end of file