docs: clarify feature stages criteria and support expectations

stirby · stirby · commit 7473439ebbdd · 2025-12-09T23:10:04.000Z
Updates the feature stages documentation to reflect internal agreements:

Early Access (EA):
- Clarify EA features are referred to internally as MVP, Phase 1, or Alpha
- Detail customer expectations: rough edges, missing features, bugs expected
- Update support: no support/SLA, escalated directly to product team
- Confirm opt-in only via CODER_EXPERIMENTS
- Add experimental naming convention requirement for API/CLI

Beta:
- Remove statement that beta features are enabled by default
- Clarify beta features are opt-in but discoverable without experiment flags
- Emphasize stable API goal between Beta and GA
- State beta features are generally feature-complete (focus on stability)
- Update support: best effort (no SLA), ~60% escalated to product team

GA:
- Add transition criteria: stability, scale, compatibility, 80% use cases
- Clarify most GA features enabled by default, but config-heavy features
  (like Prebuilds) may remain opt-in by design
- Emphasize documentation as single source of truth with air-gapped
  deployment instructions
diff --git a/docs/install/releases/feature-stages.md b/docs/install/releases/feature-stages.md
@@ -9,32 +9,38 @@ If you encounter an issue with any Coder feature, please submit a
 
 ## Feature stages
 
-| Feature stage                          | Stable | Production-ready | Support               | Description                                                                                                                   |
-|----------------------------------------|--------|------------------|-----------------------|-------------------------------------------------------------------------------------------------------------------------------|
-| [Early Access](#early-access-features) | No     | No               | GitHub issues         | For staging only. Not feature-complete or stable. Disabled by default.                                                        |
-| [Beta](#beta)                          | No     | Not fully        | Docs, Discord, GitHub | Publicly available. In active development with minor bugs. Suitable for staging; optional for production. Not covered by SLA. |
-| [GA](#general-availability-ga)         | Yes    | Yes              | License-based         | Stable and tested. Enabled by default. Fully documented. Support based on license.                                            |
+| Feature stage                          | Stable | Production-ready | Support                    | Description                                                                                                           |
+|----------------------------------------|--------|------------------|----------------------------|-----------------------------------------------------------------------------------------------------------------------|
+| [Early Access](#early-access-features) | No     | No               | No support (GitHub issues) | For staging only. Not feature-complete or stable. Disabled by default.                                                |
+| [Beta](#beta)                          | No     | Not fully        | Best effort (no SLA)       | Publicly available. Mostly stable with minor bugs. Suitable for staging; optional for production. Not covered by SLA. |
+| [GA](#general-availability-ga)         | Yes    | Yes              | License-based              | Stable and tested. Fully documented. Support based on license.                                                        |
 
 ## Early access features
 
 - **Stable**: No
 - **Production-ready**: No
-- **Support**: GitHub issues
+- **Support**: No support, no SLA. Bugs, feature requests, and feedback are
+  escalated directly to the product team. You can submit feedback through
+  [GitHub issues](https://github.com/coder/coder/issues).
 
-Early access features are neither feature-complete nor stable. We do not
-recommend using early access features in production deployments.
+Early access features are neither feature-complete nor stable.
+**Do not use early access features in production deployments.**
 
-Coder sometimes releases early access features that are available for use, but
-are disabled by default. You shouldn't use early access features in production
-because they might cause performance or stability issues. Early access features
-can be mostly feature-complete, but require further internal testing and remain
-in the early access stage for at least one month.
+Early access features are also referred to internally as MVP, Phase 1, or Alpha.
+These features are rough around the edges, may be missing functionality, and
+bugs are expected. Coder may make significant changes to or completely remove
+early access features at any time.
 
-Coder may make significant changes or revert features to a feature flag at any
-time.
+### Early access feature requirements
 
-If you plan to activate an early access feature, we suggest that you use a
-staging deployment.
+- **Opt-in only**: Early access features are always disabled by default.
+  Administrators must explicitly enable them, typically via a server flag such
+  as `CODER_EXPERIMENTS`.
+- **Experimental naming**: API routes and CLI commands for early access features
+  use "experimental" naming conventions. These experimental routes are
+  deprecated when the feature moves to Beta.
+- **Staging only**: If you plan to test an early access feature, use a staging
+  deployment.
 
 <details><summary>To enable early access features:</summary>
 
@@ -74,31 +80,43 @@ stable release.
 
 - **Stable**: No
 - **Production-ready**: Not fully
-- **Support**: Documentation, [Discord](https://discord.gg/coder), and
-  [GitHub issues](https://github.com/coder/coder/issues)
-
-Beta features are open to the public and are tagged with a `Beta` label.
-
-They’re in active development and subject to minor changes. They might contain
-minor bugs, but are generally ready for use.
-
-Beta features are often ready for general availability within two-three
-releases. You should test beta features in staging environments. You can use
-beta features in production, but should set expectations and inform users that
-some features may be incomplete.
-
-We keep documentation about beta features up-to-date with the latest
-information, including planned features, limitations, and workarounds. If you
+- **Support**: Best effort support (no SLA). Approximately 60% of support
+  tickets are escalated to the product team. You can also reach out via
+  [Documentation](../../README.md), [Discord](https://discord.gg/coder), and
+  [GitHub issues](https://github.com/coder/coder/issues).
+
+Beta features are publicly available and tagged with a `Beta` label. They are
+generally stable with a mostly complete feature set, though minor bugs may
+exist.
+
+### Beta feature characteristics
+
+- **Opt-in**: Beta features are not enabled by default. Unlike Early Access
+  features, Beta features can be naturally discovered via the product and
+  documentation without requiring `CODER_EXPERIMENTS` flags. Administrators can
+  enable them through standard configuration.
+- **Stable API**: The goal for Beta is to achieve a generally stable feature set
+  and API. Significant API changes are not expected between Beta and GA.
+- **Feature complete**: Beta features generally contain the same features as GA.
+  The focus between Beta and GA is on stability and bug fixes, not adding new
+  functionality.
+- **Production optional**: You can use Beta features in production, but should
+  inform users that some rough edges may exist. We recommend testing in staging
+  environments first.
+
+Beta features are typically ready for general availability within two to three
+releases. We keep documentation about Beta features up-to-date with the latest
+information, including planned features, limitations, and workarounds.
+
+Beta features are not covered within service-level agreements (SLA). If you
 encounter an issue, please contact your
 [Coder account team](https://coder.com/contact), reach out on
 [Discord](https://discord.gg/coder), or create a
-[GitHub issues](https://github.com/coder/coder/issues) if there isn't one
-already. While we will do our best to provide support with beta features, most
-issues will be escalated to the product team. Beta features are not covered
-within service-level agreements (SLA).
+[GitHub issue](https://github.com/coder/coder/issues) if there isn't one
+already.
 
-Most beta features are enabled by default. Beta features are announced through
-the [Coder Changelog](https://coder.com/changelog), and more information is
+Beta features are announced through the
+[Coder Changelog](https://coder.com/changelog), and more information is
 available in the documentation.
 
 ## General Availability (GA)
@@ -108,23 +126,43 @@ available in the documentation.
 - **Support**: Yes, [based on license](https://coder.com/pricing).
 
 All features that are not explicitly tagged as `Early access` or `Beta` are
-considered generally available (GA). They have been tested, are stable, and are
-enabled by default.
+considered generally available (GA). They have been tested and are stable.
+
+### Transition from Beta to GA
+
+The transition from Beta to GA focuses primarily on:
+
+- **Stability**: Ensuring the feature works reliably across various conditions.
+- **Scale**: Verifying performance under production workloads.
+- **Compatibility**: Testing across a wider set of Coder versions and
+  environments.
+
+A feature should fit at least 80% of planned use cases before reaching GA.
+
+### GA feature characteristics
+
+- **Enabled by default**: Most GA features are enabled by default. However,
+  features that require extra configuration (such as Prebuilds or external
+  integrations) may remain opt-in by design, even in GA.
+- **Full documentation**: GA features have complete documentation that outlines
+  how to use or implement the feature, including configuration options,
+  troubleshooting, and instructions for disabling features in air-gapped
+  deployments where applicable.
 
 If your Coder license includes an SLA, please consult it for an outline of
 specific expectations.
 
 For support, consult our knowledgeable and growing community on
 [Discord](https://discord.gg/coder), or create a
 [GitHub issue](https://github.com/coder/coder/issues) if one doesn't exist
-already. Customers with a valid Coder license, can submit a support request or
+already. Customers with a valid Coder license can submit a support request or
 contact your [account team](https://coder.com/contact).
 
 We intend [Coder documentation](../../README.md) to be the
 [single source of truth](https://en.wikipedia.org/wiki/Single_source_of_truth)
-and all features should have some form of complete documentation that outlines
-how to use or implement a feature. If you discover an error or if you have a
-suggestion that could improve the documentation, please
+and all features should have complete documentation that outlines how to use or
+implement a feature. If you discover an error or if you have a suggestion that
+could improve the documentation, please
 [submit a GitHub issue](https://github.com/coder/internal/issues/new?title=request%28docs%29%3A+request+title+here&labels=["customer-feedback","docs"]&body=please+enter+your+request+here).
 
 Some GA features can be disabled for air-gapped deployments. Consult the
