Compare commits

...

5 Commits

Author SHA1 Message Date
Stephen Kirby 12f80c5b31 docs: clarify that post-GA changes are incremental or by request 2025-12-09 23:36:54 +00:00
Stephen Kirby b0acae16f9 docs: clarify beta support escalation and resolution process 2025-12-09 23:34:37 +00:00
Stephen Kirby f44202bae2 docs: strengthen staging recommendation for early access features 2025-12-09 23:33:03 +00:00
Stephen Kirby b08196e7f3 docs: clarify beta API stability and timeline wording 2025-12-09 23:30:06 +00:00
Stephen Kirby 7473439ebb 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
2025-12-09 23:10:04 +00:00
+80 -40
View File
@@ -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.
<details><summary>To enable early access features:</summary>
@@ -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)
- **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 open to the public and are tagged with a `Beta` label.
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.
Theyre in active development and subject to minor changes. They might contain
minor bugs, but are generally ready for use.
### Beta feature characteristics
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.
- **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.
We keep documentation about beta features up-to-date with the latest
information, including planned features, limitations, and workarounds. If you
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