Skip to content
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

Adopt AIP-205: Beta-blocking changes #138

Merged
merged 9 commits into from
May 15, 2024
Merged
Show file tree
Hide file tree
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 45 additions & 3 deletions aep/general/0205/aep.md.j2
Original file line number Diff line number Diff line change
@@ -1,5 +1,47 @@
# Beta-blocking changes

**Note:** This AEP has not yet been adopted. See
[this GitHub issue](https://github.com/aep-dev/aep.dev/issues/50) for more
information.
APIs often release an Alpha version of their API in order to get early feedback
rofrankel marked this conversation as resolved.
Show resolved Hide resolved
from customers. This API is provisional and can change many times before the
important feedback is incorporated and the API is made stable for Beta.

Since the purpose of Alpha is to gather feedback, the API does not need to be
perfect yet, and it's not strictly necessary for API authors to address every
usability concern or address every point in the API standards. Often, API
authors and API reviewers will not agree on the best design, and the best way
to find out is by having users try out the API.

However, once the feedback has been collected and the API is going to be
promoted to Beta, usability concerns and style issues do need to be addressed.
rofrankel marked this conversation as resolved.
Show resolved Hide resolved
In order to ensure that these issues are not forgotten, they should be
rofrankel marked this conversation as resolved.
Show resolved Hide resolved
explicitly documented in the API.

## Guidance

If an API has usability concerns or violates API standards, and the present
design should receive additional scrutiny before being carried through to the
Beta version, there **must** be an internal comment linking to this document
using its descriptive link ([aep.dev/beta-blocker]()) to ensure that the design
rofrankel marked this conversation as resolved.
Show resolved Hide resolved
is corrected before the API is released to Beta.

The comment **must** also indicate what kind of change should be made for Beta.
For example:

{% tab proto %}

```proto
message InputConfig {
// Parameters for input.
// (-- aep.dev/beta-blocker: Convert well-known parameters into explicit
// fields before the Beta launch. --)
map<string, string> parameters = 1;
}
```

{% tab oas %}

**Note:** OAS example not yet written.
rofrankel marked this conversation as resolved.
Show resolved Hide resolved

{% endtabs %}

If an exception to API standards _does_ need to be carried through to Beta and
GA, see AEP-200.
2 changes: 1 addition & 1 deletion aep/general/0205/aep.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,6 @@
id: 205
state: reviewing
rofrankel marked this conversation as resolved.
Show resolved Hide resolved
slug: beta-blocking-changes
created: 2023-01-22
created: 2024-03-14
placement:
category: governance
Loading