diff --git a/docs/install/releases/feature-stages.md b/docs/install/releases/feature-stages.md index 708320422cd91..e0d2073d7f86b 100644 --- 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**: When testing out early access features, we strongly advise + using a staging deployment.
To enable early access features: @@ -74,31 +80,44 @@ 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). Most support tickets for beta + features are escalated directly to the product team. These issues will be + resolved with changes to the feature in subsequent releases or a patch. You + can also reach out via [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. +- **Generally Stable API, without Guarantees**: 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 will typically be 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,8 +127,29 @@ 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. Any +changes after GA are incremental improvements or made by customer request. + +### 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. @@ -117,14 +157,14 @@ 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