add API version progression guidelines

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

guides/api-design.md

@@ -103,9 +103,30 @@ Finally on addition of a new API, there may be addition of the capability to eit
 - Ensure successful execution of existing conformance and certification tests for any modified components
 
 
+## 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-->
 
-## Progression of an API/Building block
+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
+
+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.
+- 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.
+
+Example Scenario:
+Consider v3.0 of JS SDK supporting the Config API in Alpha stage and Dapr runtime v1.10. The Config API is promoted to Stable in v1.11 of the runtime. If between v1.10 Dapr and v1.11 Dapr runtime there are no breaking changes in the Config API then both Path/`v1.0-alpha1`/Method`Alpha1` and Path/`v1.0`/Method must be supported by the Dapr runtime.
 
+Then the SDK can be updated independent of the runtime i.e. v3.0 version of JS SDK will still continue to work with the v1.11 runtime Config API.
+
+If there are breaking changes in the Config API then only Path/`v1.0`/Method must be supported by the Dapr runtime. In this case, the SDKs must be updated to use the new path/methods. In this case only the newer version of the SDK will work with the newer version of the runtime.
+
+> Note: This guidance is specifically for Dapr runtime SDK compatibility. SDKs may have their own way of exposing/differentiating between Alpha and Stable APIs.
+
+## Progression of an API/Building block
 ### Alpha to Beta
 
 In addition to the requirements that are required of any Alpha API, the following requirements must be met so that the API can graduate to Beta. For an API to be promoted to Beta, it must exist for at least one release cycle after its initial addition as Alpha. (i.e something added in 1.10 could become  Beta in 1.12, having been stabilized through 1.11)
@@ -131,6 +152,7 @@ For **building blocks** to progress, the following criteria are required:
 
 In addition to the requirements for a Beta API, the following requirements must be met so that the API can graduate to Stable. Similar to the previous phase change, this API must have been in the Beta phase for at least one full release _without any breaking changes_. In addition, the following criteria apply:
 
+* Change API version based on the [API version progression guidelines](#progression-of-api-version-to-stable)
 * E2E scenarios must be well defined and comprehensive
 * Performance tests must be added(in case a new building block does not have performance tests in the Alpha/Beta stage)/updated
 * Expected performance data must be added to documentation

templates/lifecycle.md

@@ -14,7 +14,7 @@ Links to any relevant resources go here:
 
 ## Alpha / Beta / Stable
 
-For each stage, identify the expectations of this feature at that stage. For example, 
+For each stage, identify the expectations of this feature at that stage. For example,
 are there any performance issues, configuration changes or feature deprecation that will happen?
 
 * Anticipated performance / known limitations
@@ -63,15 +63,17 @@ Additionally, for **building blocks**:
 Additionally, for **building blocks**:
 
 - [ ] Conformance tests updated to match any API changes that have been made
-- [ ] Conformance tests exercise both positive and negative cases 
-- [ ] Minimum of N (three?) implementations of this building block 
-- [ ] Certification tests for implementations 
+- [ ] Conformance tests exercise both positive and negative cases
+- [ ] Minimum of N (three?) implementations of this building block
+- [ ] Certification tests for implementations
 - [ ] APIs that are used in the building block also meet Beta criteria
 
 
-## Stable 
-
+## Stable
 
+- [ ] Change API version to stable. See [Stable API Versioning](../guides/api-design.md#progression-of-api-version-to-stable)
+  - [ ] HTTP `v1.0-suffix` to `v1.0`
+  - [ ] gRPC `MethodSuffix` to `Method`
 - [ ] Documentation is complete in `dapr/docs` with any changes since Beta
 - [ ] E2E scenarios well defined and comprehensive
 - [ ] Performance tests exist and regressions will prevent them from successfully passing