Skip to content

docs: clarify feature stages criteria and support expectations #21196

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
stirby wants to merge 5 commits into
base: main
Choose a base branch
from
Open

docs: clarify feature stages criteria and support expectations #21196

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
7473439
docs: clarify feature stages criteria and support expectations
stirby Dec 9, 2025
b08196e
docs: clarify beta API stability and timeline wording
stirby Dec 9, 2025
f44202b
docs: strengthen staging recommendation for early access features
stirby Dec 9, 2025
b0acae1
docs: clarify beta support escalation and resolution process
stirby Dec 9, 2025
12f80c5
docs: clarify that post-GA changes are incremental or by request
stirby Dec 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
128 changes: 84 additions & 44 deletions docs/install/releases/feature-stages.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
Copy link
Contributor

@dannykopping dannykopping Dec 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Offering no support is the opposite of what EA is about. Early feedback is an absolute gift, and it has an outsized influence over future product direction.

| [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>

Expand Down Expand Up @@ -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.
Comment on lines +89 to +91
Copy link
Collaborator

@david-fraley david-fraley Dec 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider a callout to the "### Transition from Beta to GA" here as my mind immediately was like ok well what about that


### 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)
Expand All @@ -108,23 +127,44 @@ 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.
Comment on lines +138 to +139
Copy link
Collaborator

@david-fraley david-fraley Dec 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- **Compatibility**: Testing across a wider set of Coder versions and
environments.
- **Compatibility**: Testing across a wider set of Coder versions and
environments, as well as integration into the broader Coder product suite.

Trying to call out that compatibility means with our diff released versions but also with the other product lines we have, ex. DevContainers and Tasks as the most recent missing-example.

I could also see this as new bullet if you prefer like:

- **Integration**: Having integrated the feature into the broader Coder product suite
- ```


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.
Comment on lines +141 to +142
Copy link
Member

@bpmct bpmct Dec 10, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe I was the one who said this, but seeing in writing, I'm not a fan of this verbiage... I'd rather reword it to something like:

  • "A feature should be GA when it is generally useful to a wide audience, even if there are additional capabilities/use cases planned. GA does not signify feature-complete, it represents a feature being stable and useful for enterprises."


### 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.
Comment on lines +146 to +148
Copy link
Collaborator

@david-fraley david-fraley Dec 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps rephrase to

Suggested change
- **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.
- **Available by default**: All GA features are available to customers based on their licensing. However, some features that require extra configuration or additional setup (such as Prebuilds or external integrations) will not be enabled by default and will remain opt-in by design, even in GA.

Trying to distinguish "enabled's" usage from enable for release vs enabled for usage. Open to thoughts here

- **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
Expand Down
Loading