clarify when alpha suffixed paths will be removed

Signed-off-by: Mukundan Sundararajan <[email protected]>

guides/api-design.md

@@ -81,38 +81,17 @@ _Backwards-**compatible** changes_
 * May be proposed to _any_ API
 * Proposed changes to both the HTTP and gRPC API must be included
 
-
-## Requirements for Building Block changes
-
-Finally on addition of a new API, there may be addition of the capability to either an existing component or if it is a new building block, creation of a new set of components in the `dapr/components-contrib` repo.
-
-### Creating new API as part of a new building block in `dapr/components-contrib`**
-
-- Interfaces to be used by `dapr/dapr` code must be defined and agreed upon
-- New building block package is defined in `components-contrib` repo, new code must only be added inside that building block package
-- Conformance tests enable validating the components compliance with defined interface for the building block and creates a baseline for conformance testing any new components added. Conformance tests may be added for the new API with the understanding that it may evolve
-
-
-### Creating new API for an existing building block in `dapr/components-contrib`
-
-- Interfaces changes for the new API must be defined and agreed upon
-- Existing components that support the new API must be enhanced to be in compliance with the proposed interface as per the defined and agreed upon scope of the original proposal
-- Conformance tests must be updated
-  - Get sign off on a basic suite of conformance tests for the interface method(s)
-  - Implement the suite of conformance tests as part of the existing suite of tests for the building block
-- Ensure successful execution of existing conformance and certification tests for any modified components
-
-
-## Progression of API version to Stable
+### Progression of API version to Stable
 <!-- TODO: change this when once this issue relating to Beta is decided https://github.com/dapr/proposals/issues/13-->
 
 Currently for HTTP API, the non-stable API has the path `v1.0-alpha1` instead of stable APIs having the form `v1.0`. Similarly for gRPC, the non-stable API has the suffix `Alpha1` added to the gRPC methods.
 SDKs implementing the API before the stable release use the above mentioned paths/methods for HTTP and gRPC respectively. Once the API is promoted to stable, the SDKs must be updated to use the stable paths/methods.
 
-### Compatibility
+#### Compatibility
 
 To cater to the scenario where an older SDK is accessing a newer version of Dapr, the following compatibility rules must be followed:
 - If there are no breaking changes in the API(User request/response) from the prior version to the version it is made stable, then both the old and new paths/methods must be supported by the Dapr runtime.
+  - The `alpha` suffixed API paths/methods must be removed from the Dapr runtime once all _core_ SDKs have been updated (preferrably in the next Dapr release). Removal of the `alpha` suffixed API is still considered a breaking change and must be documented in the release notes as such.
 - If there are breaking changes in the API(User request/response) from the prior version to the version it is made stable, then only the new paths/methods must be supported by the Dapr runtime. The old paths/methods must be removed from the Dapr runtime.
 
 > Note: The components themselves might have breaking changes, that will not affect the API version progression.
@@ -126,6 +105,26 @@ If there are breaking changes in the Config API then only Path/`v1.0`/Method mus
 
 > Note: This guidance is specifically for Dapr runtime SDK compatibility. SDKs may have their own way of exposing/differentiating between Alpha and Stable APIs.
 
+## Requirements for Building Block changes
+
+Finally on addition of a new API, there may be addition of the capability to either an existing component or if it is a new building block, creation of a new set of components in the `dapr/components-contrib` repo.
+
+### Creating new API as part of a new building block in `dapr/components-contrib`**
+
+- Interfaces to be used by `dapr/dapr` code must be defined and agreed upon
+- New building block package is defined in `components-contrib` repo, new code must only be added inside that building block package
+- Conformance tests enable validating the components compliance with defined interface for the building block and creates a baseline for conformance testing any new components added. Conformance tests may be added for the new API with the understanding that it may evolve
+
+
+### Creating new API for an existing building block in `dapr/components-contrib`
+
+- Interfaces changes for the new API must be defined and agreed upon
+- Existing components that support the new API must be enhanced to be in compliance with the proposed interface as per the defined and agreed upon scope of the original proposal
+- Conformance tests must be updated
+  - Get sign off on a basic suite of conformance tests for the interface method(s)
+  - Implement the suite of conformance tests as part of the existing suite of tests for the building block
+- Ensure successful execution of existing conformance and certification tests for any modified components
+
 ## Progression of an API/Building block
 ### Alpha to Beta