From 7473439ebbdd827ed2c968c4d78709100378beb2 Mon Sep 17 00:00:00 2001 From: Stephen Kirby Date: Tue, 9 Dec 2025 23:10:04 +0000 Subject: [PATCH 1/5] docs: clarify feature stages criteria and support expectations 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 --- docs/install/releases/feature-stages.md | 126 +++++++++++++++--------- 1 file changed, 82 insertions(+), 44 deletions(-) diff --git a/docs/install/releases/feature-stages.md b/docs/install/releases/feature-stages.md index 708320422cd91..5c8ba65af8cda 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**: If you plan to test an early access feature, use a staging + deployment.
To enable early access features: @@ -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,8 +126,28 @@ 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. @@ -117,14 +155,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 From b08196e7f3cc819e2a43f305450f1edce56819b6 Mon Sep 17 00:00:00 2001 From: Stephen Kirby Date: Tue, 9 Dec 2025 23:30:06 +0000 Subject: [PATCH 2/5] docs: clarify beta API stability and timeline wording --- docs/install/releases/feature-stages.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/install/releases/feature-stages.md b/docs/install/releases/feature-stages.md index 5c8ba65af8cda..9a515305129b4 100644 --- a/docs/install/releases/feature-stages.md +++ b/docs/install/releases/feature-stages.md @@ -95,7 +95,7 @@ exist. 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 +- **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 @@ -104,7 +104,7 @@ exist. 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 +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. From f44202bae2d03abe098da21225c50341f8f8c81d Mon Sep 17 00:00:00 2001 From: Stephen Kirby Date: Tue, 9 Dec 2025 23:33:03 +0000 Subject: [PATCH 3/5] docs: strengthen staging recommendation for early access features --- docs/install/releases/feature-stages.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/install/releases/feature-stages.md b/docs/install/releases/feature-stages.md index 9a515305129b4..4816e65acf637 100644 --- a/docs/install/releases/feature-stages.md +++ b/docs/install/releases/feature-stages.md @@ -39,8 +39,8 @@ early access features at any time. - **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. +- **Staging only**: When testing out early access features, we strongly advise + using a staging deployment.
To enable early access features: From b0acae16f9937ae173a53ab56aceab0d418814bd Mon Sep 17 00:00:00 2001 From: Stephen Kirby Date: Tue, 9 Dec 2025 23:34:37 +0000 Subject: [PATCH 4/5] docs: clarify beta support escalation and resolution process --- docs/install/releases/feature-stages.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/install/releases/feature-stages.md b/docs/install/releases/feature-stages.md index 4816e65acf637..e5a195238fc43 100644 --- a/docs/install/releases/feature-stages.md +++ b/docs/install/releases/feature-stages.md @@ -80,9 +80,10 @@ stable release. - **Stable**: No - **Production-ready**: Not fully -- **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 +- **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 From 12f80c5b314c94c16dddffdaa4662f693e4396af Mon Sep 17 00:00:00 2001 From: Stephen Kirby Date: Tue, 9 Dec 2025 23:36:54 +0000 Subject: [PATCH 5/5] docs: clarify that post-GA changes are incremental or by request --- docs/install/releases/feature-stages.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/install/releases/feature-stages.md b/docs/install/releases/feature-stages.md index e5a195238fc43..e0d2073d7f86b 100644 --- a/docs/install/releases/feature-stages.md +++ b/docs/install/releases/feature-stages.md @@ -138,7 +138,8 @@ The transition from Beta to GA focuses primarily on: - **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. +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