feat: introduce api leveling documentation

this document outlines different API stability levels, how to enforce them, and next steps

Signed-off-by: Charlie Doern <[email protected]>

Author: cdoern

docs/source/apis/api_leveling.md

@@ -0,0 +1,57 @@
+# Llama Stack API Stability Leveling
+
+In order to provide a stable experience in Llama Stack, the various APIs need different stability levels indicating the level of support, backwards compatability, and overall production readiness.
+
+## Different Levels
+
+### v1alpha1
+
+- Little to no expectation of support between versions
+- Breaking changes are permitted
+- Datatypes and parameters can break
+- Routes can be added and removed
+
+### v1beta1
+
+- API routes ensured between versions
+- Parameters and return types are not
+- API, besides minor fixes and adjustments, should be _almost_ v1. Changes should not be drastic.
+
+### v1 (stable)
+
+- Considered stable
+- Backwards compatible between Z-streams
+  - Y-stream breaking changes must go through the proper approval and announcement process.
+- Datatypes for a route and its return types cannot changed between Z-streams
+  - Y-stream datatype changes should be sparing, unless the changes are additional net-new parameters
+- Must have proper conformance testing as outlined in https://github.com/llamastack/llama-stack/issues/3237
+
+
+### Approval and Announcement Process for Breaking Changes
+
+- **PR Labeling**: Any pull request that introduces a breaking API change must be clearly labeled with `breaking-change`.
+- **Changelog Entry**: The PR must also update the changelog to describe the change, its impact, and any migration steps.
+- **Maintainer Review**: At least one maintainer must explicitly acknowledge the breaking change during review.
+- **Announcement**: Breaking changes require inclusion in release notes and, if applicable, a separate communication (e.g., mailing list, Slack, or GitHub Discussions) prior to release.
+
+## Enforcement
+
+### Migration of API routes under `/v1alpha1`, `/v1beta1`, and `/v1`
+
+Instead of placing every API under `/v1`, any API that is not fully stable or complete should go under `/v1alpha1` or `/v1beta1`. For example, at the time of this writing,  `post_training` belongs here, as well as any OpenAI-compatible API whose surface does not exactly match the upstream OpenAI API it mimics.
+
+This migration is crucual as we get Llama Stack in the hands of users who intend to productize various APIs. A clear view of what is stable and what is actively being developed will enable users to pick and choose various APIs to build their products on.
+
+This migration will be a breaking change for any api moving out of `/v1`. Ideally, this should happen before 0.3.0 and especially 1.0.0.
+
+### `x-stability` tags in the OpenAPI spec for oasdiff
+
+`x-stability` tags allow tools like oasdiff to enforce different rules for different stability levels; these tags should match the routes: [oasdiff stability](https://github.com/oasdiff/oasdiff/blob/main/docs/STABILITY.md)
+
+### Testing
+
+The testing of each stable API is already outlined in [issue #3237](https://github.com/llamastack/llama-stack/issues/3237) and is being worked on. These sorts of conformance tests should apply primarily to `/v1` APIs only, with `/v1alpha` and `/v1beta1` having any tests the maintainers see fit as well as basic testing to ensure the routing works properly.
+
+## Next Steps
+
+Following the adoption of this document, all existing APIs should follow the enforcement protocol, and any subsequently introduced APIs should be introduced as `/v1alpha1`