From 91e4103e00b960262233bd495a5fcf6f7a4277d0 Mon Sep 17 00:00:00 2001 From: Richard Frankel Date: Thu, 14 Mar 2024 13:10:23 -0500 Subject: [PATCH 1/8] Adopt AIP-205: Beta-blocking changes --- aep/general/0205/aep.md.j2 | 42 +++++++++++++++++++++++++++++++++++--- aep/general/0205/aep.yaml | 2 +- 2 files changed, 40 insertions(+), 4 deletions(-) diff --git a/aep/general/0205/aep.md.j2 b/aep/general/0205/aep.md.j2 index 24c65be4..25c17db1 100644 --- a/aep/general/0205/aep.md.j2 +++ b/aep/general/0205/aep.md.j2 @@ -1,5 +1,41 @@ # 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 +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. +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 ([aip.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: + +```proto +message InputConfig { + // Parameters for input. + // (-- aip.dev/beta-blocker: Convert well-known parameters into explicit + // fields before the Beta launch. --) + map parameters = 1; +} +``` + +If an exception to API standards _does_ need to be carried through to Beta and +GA, see [AIP-200][]. + +[aip-200]: ./0200.md \ No newline at end of file diff --git a/aep/general/0205/aep.yaml b/aep/general/0205/aep.yaml index 843ece9a..009eca69 100644 --- a/aep/general/0205/aep.yaml +++ b/aep/general/0205/aep.yaml @@ -2,6 +2,6 @@ id: 205 state: reviewing slug: beta-blocking-changes -created: 2023-01-22 +created: 2024-03-14 placement: category: governance From a18477b95d5ac82c70423c53c039c981ddedd150 Mon Sep 17 00:00:00 2001 From: Richard Frankel Date: Thu, 14 Mar 2024 13:11:12 -0500 Subject: [PATCH 2/8] De-Google --- aep/general/0205/aep.md.j2 | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/aep/general/0205/aep.md.j2 b/aep/general/0205/aep.md.j2 index 25c17db1..9016add9 100644 --- a/aep/general/0205/aep.md.j2 +++ b/aep/general/0205/aep.md.j2 @@ -20,7 +20,7 @@ explicitly documented in the API. 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 ([aip.dev/beta-blocker]()) to ensure that the design +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. @@ -29,13 +29,11 @@ For example: ```proto message InputConfig { // Parameters for input. - // (-- aip.dev/beta-blocker: Convert well-known parameters into explicit + // (-- aep.dev/beta-blocker: Convert well-known parameters into explicit // fields before the Beta launch. --) map parameters = 1; } ``` If an exception to API standards _does_ need to be carried through to Beta and -GA, see [AIP-200][]. - -[aip-200]: ./0200.md \ No newline at end of file +GA, see AEP-200. From e23d733d8dc40f561647d5071d2383164235eb90 Mon Sep 17 00:00:00 2001 From: Richard Frankel Date: Thu, 14 Mar 2024 13:11:59 -0500 Subject: [PATCH 3/8] Add proto/OAS tabs --- aep/general/0205/aep.md.j2 | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/aep/general/0205/aep.md.j2 b/aep/general/0205/aep.md.j2 index 9016add9..b80e8503 100644 --- a/aep/general/0205/aep.md.j2 +++ b/aep/general/0205/aep.md.j2 @@ -26,6 +26,8 @@ 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. @@ -35,5 +37,11 @@ message InputConfig { } ``` +{% tab oas %} + +**Note:** OAS example not yet written. + +{% endtabs %} + If an exception to API standards _does_ need to be carried through to Beta and GA, see AEP-200. From 2a99ba4cec1075a020ceb5680c0252655fb58b89 Mon Sep 17 00:00:00 2001 From: Richard Frankel Date: Mon, 18 Mar 2024 15:15:02 -0400 Subject: [PATCH 4/8] Update aep/general/0205/aep.yaml Co-authored-by: Yusuke Tsutsumi --- aep/general/0205/aep.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aep/general/0205/aep.yaml b/aep/general/0205/aep.yaml index 009eca69..cce5cd21 100644 --- a/aep/general/0205/aep.yaml +++ b/aep/general/0205/aep.yaml @@ -1,6 +1,6 @@ --- id: 205 -state: reviewing +state: approved slug: beta-blocking-changes created: 2024-03-14 placement: From cc25d4e9725d68b10ee792e949ab4a21b6cfbdf1 Mon Sep 17 00:00:00 2001 From: Richard Frankel Date: Mon, 18 Mar 2024 15:17:33 -0400 Subject: [PATCH 5/8] Update aep/general/0205/aep.md.j2 Co-authored-by: Yusuke Tsutsumi --- aep/general/0205/aep.md.j2 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aep/general/0205/aep.md.j2 b/aep/general/0205/aep.md.j2 index b80e8503..b82b7383 100644 --- a/aep/general/0205/aep.md.j2 +++ b/aep/general/0205/aep.md.j2 @@ -11,7 +11,7 @@ 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. +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. From 74a4d2abe7fce9cd89cb9a2fbeec9a5ba08e5856 Mon Sep 17 00:00:00 2001 From: Richard Frankel Date: Mon, 18 Mar 2024 15:17:38 -0400 Subject: [PATCH 6/8] Update aep/general/0205/aep.md.j2 Co-authored-by: Yusuke Tsutsumi --- aep/general/0205/aep.md.j2 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aep/general/0205/aep.md.j2 b/aep/general/0205/aep.md.j2 index b82b7383..10502218 100644 --- a/aep/general/0205/aep.md.j2 +++ b/aep/general/0205/aep.md.j2 @@ -12,7 +12,7 @@ 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 +In order to ensure that these issues are not forgotten, they **should** be explicitly documented in the API. ## Guidance From bcdb25027b9a78e76db217ff57e67c44f7eafae2 Mon Sep 17 00:00:00 2001 From: Richard Frankel Date: Mon, 18 Mar 2024 14:18:23 -0500 Subject: [PATCH 7/8] Cleanup in response to PR comments --- aep/general/0205/aep.md.j2 | 20 ++++++++++---------- aep/general/0205/aep.yaml | 1 + 2 files changed, 11 insertions(+), 10 deletions(-) diff --git a/aep/general/0205/aep.md.j2 b/aep/general/0205/aep.md.j2 index b80e8503..fdb6b6ea 100644 --- a/aep/general/0205/aep.md.j2 +++ b/aep/general/0205/aep.md.j2 @@ -1,17 +1,17 @@ -# Beta-blocking changes +# beta-blocking changes -APIs often release an Alpha version of their API in order to get early feedback +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. +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 +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. +promoted to beta, usability concerns and style issues do need to be addressed. In order to ensure that these issues are not forgotten, they should be explicitly documented in the API. @@ -19,11 +19,11 @@ explicitly documented in the API. 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 +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. +is corrected before the API is released to beta. -The comment **must** also indicate what kind of change should be made for Beta. +The comment **must** also indicate what kind of change should be made for beta. For example: {% tab proto %} @@ -32,7 +32,7 @@ For example: message InputConfig { // Parameters for input. // (-- aep.dev/beta-blocker: Convert well-known parameters into explicit - // fields before the Beta launch. --) + // fields before the beta launch. --) map parameters = 1; } ``` @@ -43,5 +43,5 @@ message InputConfig { {% endtabs %} -If an exception to API standards _does_ need to be carried through to Beta and +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 index 009eca69..6ddfaa0b 100644 --- a/aep/general/0205/aep.yaml +++ b/aep/general/0205/aep.yaml @@ -5,3 +5,4 @@ slug: beta-blocking-changes created: 2024-03-14 placement: category: governance +redirect_from: /beta-blocker \ No newline at end of file From bfcd65575e441b45c4c6048b19e0443763de55f6 Mon Sep 17 00:00:00 2001 From: Richard Frankel Date: Wed, 15 May 2024 15:43:19 -0700 Subject: [PATCH 8/8] Fix capitalization --- aep/general/0205/aep.md.j2 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aep/general/0205/aep.md.j2 b/aep/general/0205/aep.md.j2 index 3c922059..3fda8227 100644 --- a/aep/general/0205/aep.md.j2 +++ b/aep/general/0205/aep.md.j2 @@ -1,4 +1,4 @@ -# beta-blocking changes +# 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