Skip to content

docs: redefine and clarify feature stages #18416

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

Draft
wants to merge 4 commits into
base: main
Choose a base branch
from
+93 −66
Draft

docs: redefine and clarify feature stages #18416

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
9cf2b42
redefine feature stages
EdwardAngert Jun 17, 2025
7471dfc
edits from code review
EdwardAngert Jul 1, 2025
e5f361c
make
EdwardAngert Jul 1, 2025
cabad4e
Merge branch 'main' into coder-feature-stages
EdwardAngert Jul 1, 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
159 changes: 93 additions & 66 deletions docs/install/releases/feature-stages.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,45 +1,65 @@
# Feature stages

Some Coder features are released in feature stages before they are generally
available.
We release some Coder features or components in feature stages before we consider them "generally available" (GA).

If you encounter an issue with any Coder feature, please submit a
[GitHub issue](https://github.com/coder/coder/issues) or join the
[Coder Discord](https://discord.gg/coder).
This gives Coder users the opportunity to use the latest Coder features and improve the open-source project.

If you encounter an issue with a Coder feature at any stage, please submit a
[GitHub issue](https://github.com/coder/coder/issues) if one doesn't already exist
or join the [Coder Discord](https://discord.gg/coder).

## 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 |
|-------------------------------------------|--------|------------------|-----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Experiment](#experiment-hidden) | No | No | N/A | For staging and testing only. Not feature-complete or stable.</br>Hidden and disabled by default. |
| [Early Access](#early-access-features) | No | No | Limited documentation</br>GitHub issues | For staging only. Functional, but not feature-complete or stable.</br>Disabled by default. |
Copy link
Member

Choose a reason for hiding this comment

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

This is a question for product but we often release early-access and experimental at the same time; I almost thought they were synonymous.
I agree it makes sense to separate them here but curious if we have any formal philosophy.

Copy link
Contributor Author

@EdwardAngert EdwardAngert Jul 1, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

The plan is to differentiate the two and (better) define the graduation criteria to early access - so something like:

  • experiment --> stays
  • experiment --safe --> early access

edit to add: which also means we should refine the mechanism as well. that'll make it easier to 1. choose between the two; 2. maintain/keep track of them

| [Beta](#beta) | No | Not fully | Documentation</br>Discord</br>GitHub | Publicly available on an opt-in basis. In active development with minor bugs. Suitable for staging; optional for production. |
| [GA](#general-availability-ga) | Yes | Yes | License-based / SLA | Stable and tested. Enabled by default. Fully documented. |
| [Legacy (Deprecated)](#legacy-deprecated) | Yes* | Yes* | Best-effort security updates | Legacy features continue to function, but will not be updated outside of the limits defined in a customer's license or agreement.</br>They will be removed in future versions of Coder. |

## Experiment (Hidden)

- **Stable**: No
- **Production-ready**: No
- **Support**: N/A

Experimental features are in active development and hidden by default.
They are not ready for ongoing use and aspects might be broken or can lead to data loss.

You can enable an experimental feature for testing if you want to explore the latest Coder code or if you'd like to contribute.

<details><summary>To enable an experimental feature:</summary>

Use the [Coder CLI](../../install/cli.md) `--experiments` flag to enable the feature:

```shell
coder server --experiments=featureName
```

</details>

## Early access features

- **Stable**: No
- **Production-ready**: No
- **Support**: GitHub issues
- **Support**: [Discord](https://discord.gg/coder), and [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. We do not
recommend using early access features in production deployments.
Coder sometimes releases early access features that are available for use, but are disabled by default.
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
Coder sometimes releases early access features that are available for use, but are disabled by default.
Coder sometimes releases early access features that are available for use, but are opt-in by default.

Some features are not disabled by default but require opt-in, such as Presets and the upcoming Secrets. We will likely not hide them behind a flag and provide an early access status within the product and documentation through labels.

Copy link
Member

Choose a reason for hiding this comment

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

Also they're usually opt-in via an experiment, right? Hence my above question about the difference between experimental and early-access. I feel like experimental isn't a feature stage but a way to enable a feature stage.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Secrets might be a good example to work through.

I think that's an EA feature that should be behind a feature flag (even if it's an Admin settings-style option on the dashboard).

Copy link
Member

Choose a reason for hiding this comment

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

It's not necessarily true. A feature can be shipped as EA without a flag. I think we need a larger discussion if we want to adopt hiding EA behind flags.


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

Coder may make significant changes or revert features to a feature flag at any
time.
Coder may make significant changes or revert features to [Experiment](#experiment-hidden) at any time.

If you plan to activate an early access feature, we suggest that you use a
staging deployment.
If you plan to activate an early access feature, we suggest that you use a staging deployment.

<details><summary>To enable early access features:</summary>

Use the [Coder CLI](../../install/cli.md) `--experiments` flag to enable early
access features:
Use the [Coder CLI](../../install/cli.md) `--experiments` flag to enable early access features:
Copy link
Member

Choose a reason for hiding this comment

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

It's not a hard requirement to gate all early access features behind feature flags.

I see that we are adding a new category for experimental features that could also qualify as EA.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I think that's what we're doing here - not necessarily explaining current behavior, but defining what it could/should be


- Enable all early access features:

Expand Down Expand Up @@ -80,53 +100,60 @@ You can opt-out of a feature after you've enabled it.

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.
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.
Beta features are often ready for general availability within two or 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.
Copy link
Member

Choose a reason for hiding this comment

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

We now try to complete features in Beta and only do polishing and bug fixes in the GA phase. So saying that they may be comparable feature-wise would be incorrect.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

That makes sense to me as beta too - I think of beta software as effective a release candidate, maybe some new features that need to be stress-tested, but are otherwise mostly ready


We keep documentation about beta features up-to-date with the latest
information, including planned features, limitations, and workarounds. 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).
We keep documentation about beta features up-to-date with the latest information, including planned features, limitations, and workarounds.
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).

Most beta features are enabled by default. Beta features are announced through
the [Coder Changelog](https://coder.com/changelog), and more information is
available in the documentation.
Beta features are announced through the [Coder Changelog](https://coder.com/changelog), and more information is available
in the documentation for the feature.

## General Availability (GA)

- **Stable**: Yes
- **Production-ready**: Yes
- **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.

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
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
[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
feature's documentation or submit a support ticket for assistance.
- **Support**: [Based on license](https://coder.com/pricing), [Discord](https://discord.gg/coder), and
[GitHub issues](https://github.com/coder/coder/issues)

All features that are not explicitly tagged as `Early access` or `Beta` are considered generally available (GA).
Copy link
Member

Choose a reason for hiding this comment

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

Sometimes we inline formatting for feature stages, e.g. Early access and sometimes we don't, e.g. Early access. The casing isn't consistent, either.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

😭

They have been tested, are stable, and are enabled by default.

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.
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
[GitHub issue](https://github.com/coder/coder/issues) if one doesn't exist already.
[GitHub issue](https://github.com/coder/coder/issues/new/choose) if one doesn't exist already.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I want them to search first!

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
[submit a GitHub issue](https://github.com/coder/coder/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 feature's documentation or submit a support ticket for assistance.

## Legacy (Deprecated)

Comment on lines +143 to +144
Copy link
Member

Choose a reason for hiding this comment

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

We should add Product labels and docs labels to all deprecated features.
There are a few deprecated API endpoints listed in the API docs.

- **Stable**: Yes*
- **Production-ready**: Yes*
- **Support**: Best-effort security updates

On rare occasions, the Coder team may deprecate features that have been replaced by another functionality, or that tedious to maintain.

In order to maintain stability and predictability, we avoid deprecating features that might lead to breaking changes as much as we can.
Before we deprecate a feature, we will communicate the upcoming changes and timeline to all customers and through various mediums,
and we'll provide guidance and documentation on how to ease the transition.

After the feature is deprecated, we may continue to patch security vulnerabilities or include community patches as long as we can.

*Legacy features might be stable and production ready, but there's no guarantee that they will continue working without issue or with new features and requirements.

Support is available as defined in your license or agreement.
Loading