feat(181): Import AEP-181 from AIP-181 #150
Open
+76
−5
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
notable differences are: - removed all references to Google. - slight change of formatting in "emergency changes", to clearly outline scenarios where such change are acceptable.
rofrankel
approved these changes
Mar 18, 2024
aep/general/0181/aep.md.j2
Outdated
Comment on lines
59
to
61
| 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. |
There was a problem hiding this comment.
I don't really understand how deprecation helps here. If I make a breaking change (e.g. delete a field from a resource), what would I deprecate, and what would I "continue to support"?
cfineman
reviewed
Mar 18, 2024
cfineman
reviewed
Mar 18, 2024
aep/general/0181/aep.md.j2
Outdated
| 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. |
There was a problem hiding this comment.
Is the "turndown" period specified elsewhere? I have not seen it yet... presumably this would be formally stated somewhere.
Co-authored-by: Alex Stephen <1325798+rambleraptor@users.noreply.github.com>
This was referenced Apr 28, 2024
toumorokoshi
commented
May 10, 2024
| 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.
We'l remove this from the AEP - since it's an implicit understanding of all software.
rofrankel
requested changes
May 10, 2024
| of them individually. | ||
|
|
||
| Breaking changes **must** be both allowed and expected in alpha components, and | ||
| users **must** have no expectation of stability. |
There was a problem hiding this comment.
Suggested change
| users **must** have no expectation of stability. | |
| users **must not** have an expectation of stability. |
WDYT?
| 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.
Suggested change
| but **may** include backwards-incompatible changes to beta components. | |
| but **may** include backwards-incompatible changes. |
(seems redundant)
| 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. |
There was a problem hiding this comment.
Suggested change
| This deprecation period **must** be defined at the time of being marked beta. | |
| This deprecation period **must** be defined at the time the component is declared beta. |
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 | ||
| 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.
Suggested change
| of being marked beta. A reasonable time period **may** vary, but a good rule of | |
| of being declared beta. A reasonable time period **may** vary, but a good rule of |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
notable differences are: