From 489dcd5718f0f41ae1dccf926102149f25f9881e Mon Sep 17 00:00:00 2001 From: Alex Stephen Date: Wed, 12 Nov 2025 14:40:53 -0800 Subject: [PATCH 1/2] Add OAS example for AEP-205 --- aep/general/0205/aep.md.j2 | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/aep/general/0205/aep.md.j2 b/aep/general/0205/aep.md.j2 index d5049849..4b46c69e 100644 --- a/aep/general/0205/aep.md.j2 +++ b/aep/general/0205/aep.md.j2 @@ -39,7 +39,21 @@ message InputConfig { {% tab oas %} -**Note:** OAS example not yet written. +```yaml +components: + schemas: + InputConfig: + type: object + properties: + parameters: + type: object + additionalProperties: + type: string + description: | + Parameters for input. + (-- aep.dev/beta-blocker: Convert well-known parameters into explicit + fields before the beta launch. --) +``` {% endtabs %} From a362f25b06fc7d4d3959668b5237df3d1808d8fc Mon Sep 17 00:00:00 2001 From: Alex Stephen Date: Fri, 14 Nov 2025 10:46:28 -0800 Subject: [PATCH 2/2] Remove AEP 205 --- aep/general/0205/aep.md.j2 | 61 -------------------------------------- aep/general/0205/aep.yaml | 8 ----- 2 files changed, 69 deletions(-) delete mode 100644 aep/general/0205/aep.md.j2 delete mode 100644 aep/general/0205/aep.yaml diff --git a/aep/general/0205/aep.md.j2 b/aep/general/0205/aep.md.j2 deleted file mode 100644 index 4b46c69e..00000000 --- a/aep/general/0205/aep.md.j2 +++ /dev/null @@ -1,61 +0,0 @@ -# Beta-blocking changes - -APIs often release an alpha version of their API in order to get early feedback -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 need to be addressed. In -order to ensure that these issues are not forgotten, they **should** be -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 -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 parameters = 1; -} -``` - -{% tab oas %} - -```yaml -components: - schemas: - InputConfig: - type: object - properties: - parameters: - type: object - additionalProperties: - type: string - description: | - Parameters for input. - (-- aep.dev/beta-blocker: Convert well-known parameters into explicit - fields before the beta launch. --) -``` - -{% endtabs %} - -If an exception to API standards _does_ need to be carried through to beta and -GA, see AEP-200. diff --git a/aep/general/0205/aep.yaml b/aep/general/0205/aep.yaml deleted file mode 100644 index 43fcc188..00000000 --- a/aep/general/0205/aep.yaml +++ /dev/null @@ -1,8 +0,0 @@ ---- -id: 205 -state: approved -slug: beta-blocking-changes -created: 2024-03-14 -placement: - category: governance -redirect_from: /beta-blocker