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:

Protocol Buffers

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;
}

OpenAPI 3.0

Note: OAS example not yet written.

If an exception to API standards does need to be carried through to beta and GA, see AEP-200.