docs: redefine and clarify feature stages #18416

EdwardAngert · 2025-06-17T20:17:13Z

Summary

Edit the feature stages doc to define and clarify each stage both for Coder users and internally.

Specifically:

product: deciding what a feature is and when it feature graduates or is removed
engineering: tagging and communicating risk (for any stage - esp. since this now introduces the idea of deprecation)
support: customer expectations and SLAs
docs: everywhere

in pr/in progress

added "experiment (hidden)" and "legacy (deprecated)" rows
draft deprecation policy modeled after GitLab/GitHub

todo

define graduation criteria?
add an “Enabled by default?” column or list item for each

help wanted

check wording. this effectively states policy
☝️ ensure scopes of support align with intention and SLA
Legacy/deprecation language and intent

matifali

Left a few comments and queries.

matifali · 2025-06-18T07:27:45Z

docs/install/releases/feature-stages.md

+| [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. Not covered by SLA.                                        |
+| [GA](#general-availability-ga)            | Yes    | Yes              | License-based / SLA                     | Stable and tested. Enabled by default. Fully documented. Support based on license.                                                                                                      |


We do not need to repeat support in the Description column, since we already have a separate Support column.

matifali · 2025-06-18T07:28:48Z

docs/install/releases/feature-stages.md

+| [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.                                                                                              |
+| [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. Not covered by SLA.                                        |
+| [GA](#general-availability-ga)            | Yes    | Yes              | License-based / SLA                     | Stable and tested. Enabled by default. Fully documented. Support based on license.                                                                                                      |


We should mention Discord, GitHub, and Documentation as support channels for GA features, at least for the OSS community.

matifali · 2025-06-18T07:30:41Z

docs/install/releases/feature-stages.md

-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 sometimes releases early access features that are available for use, but are disabled by default.


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.

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.

matifali · 2025-06-18T07:32:34Z

docs/install/releases/feature-stages.md


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


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.

matifali · 2025-06-18T07:33:57Z

docs/install/releases/feature-stages.md

-some features may be incomplete.
+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 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.

matifali · 2025-06-18T07:35:14Z

docs/install/releases/feature-stages.md

-already. Customers with a valid Coder license, can submit a support request or
-contact your [account team](https://coder.com/contact).
+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.


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.

matifali · 2025-06-18T07:36:16Z

docs/install/releases/feature-stages.md

-suggestion that could improve the documentation, please
+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).


Why are we asking for feedback on the internal repo? We should use the coder/coder repo issues or GitHub Discussions.

matifali · 2025-06-18T07:37:31Z

docs/install/releases/feature-stages.md

+## Legacy (Deprecated)
+


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

Kira-Pilot · 2025-06-23T15:41:50Z

docs/install/releases/feature-stages.md

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


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.

Kira-Pilot · 2025-06-23T15:42:45Z

docs/install/releases/feature-stages.md

+|-------------------------------------------|--------|------------------|-----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [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.                                                                                              |
+| [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. Not covered by SLA.                                        |


Another product question: will all beta features be opt-in? Or will some just be tagged beta?
What if something is greenfield?

Kira-Pilot · 2025-06-23T15:46:52Z

docs/install/releases/feature-stages.md

-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.
+Most beta features are enabled by default.


Are they? Above we say they're opt-in.

Kira-Pilot · 2025-06-23T15:48:30Z

docs/install/releases/feature-stages.md

-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.
+All features that are not explicitly tagged as `Early access` or `Beta` are considered generally available (GA).


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.

Kira-Pilot · 2025-06-23T15:49:51Z

Nice! Sorry for the delayed review.

redefine feature stages

9cf2b42

EdwardAngert requested a review from bpmct June 17, 2025 20:17

EdwardAngert self-assigned this Jun 17, 2025

EdwardAngert added the docs Area: coder.com/docs label Jun 17, 2025

EdwardAngert requested review from matifali, Kira-Pilot, bpmct and stirby and removed request for bpmct June 17, 2025 20:26

matifali requested changes Jun 18, 2025

View reviewed changes

Kira-Pilot reviewed Jun 23, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: redefine and clarify feature stages #18416

docs: redefine and clarify feature stages #18416

EdwardAngert commented Jun 17, 2025 •

edited

Loading

Uh oh!

matifali left a comment

Uh oh!

matifali Jun 18, 2025

Uh oh!

matifali Jun 18, 2025 •

edited

Loading

Uh oh!

matifali Jun 18, 2025

Uh oh!

Kira-Pilot Jun 23, 2025

Uh oh!

matifali Jun 18, 2025

Uh oh!

matifali Jun 18, 2025

Uh oh!

matifali Jun 18, 2025

Uh oh!

matifali Jun 18, 2025

Uh oh!

matifali Jun 18, 2025

Uh oh!

Kira-Pilot Jun 23, 2025

Uh oh!

Kira-Pilot Jun 23, 2025

Uh oh!

Kira-Pilot Jun 23, 2025

Uh oh!

Kira-Pilot Jun 23, 2025

Uh oh!

Kira-Pilot commented Jun 23, 2025

Uh oh!

Uh oh!

		\| [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. Not covered by SLA. \|
		\| [GA](#general-availability-ga) \| Yes \| Yes \| License-based / SLA \| Stable and tested. Enabled by default. Fully documented. Support based on license. \|

	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.

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

docs: redefine and clarify feature stages #18416

Are you sure you want to change the base?

docs: redefine and clarify feature stages #18416

Conversation

EdwardAngert commented Jun 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

in pr/in progress

todo

help wanted

Uh oh!

matifali left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matifali Jun 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Kira-Pilot commented Jun 23, 2025

Uh oh!

Uh oh!

EdwardAngert commented Jun 17, 2025 •

edited

Loading

matifali Jun 18, 2025 •

edited

Loading