-
Notifications
You must be signed in to change notification settings - Fork 15
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
feat(181): Import AEP-181 from AIP-181 #150
base: main
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change | ||||
---|---|---|---|---|---|---|
@@ -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. | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
(seems redundant) |
||||||
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. | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
This is more consistent with the above phrasing: "A beta component must be considered complete and ready to be declared stable..." |
||||||
|
||||||
Beta components **should** be time-boxed and promoted to stable if no issues | ||||||
toumorokoshi marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
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 | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
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 | ||||||
toumorokoshi marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
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 | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. We'l remove this from the AEP - since it's an implicit understanding of all software. |
||||||
|
||||||
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 |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
WDYT?