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
❓ can we add a section to Admin settings so people can enable pre-GA features?

matifali

Left a few comments and queries.

docs/install/releases/feature-stages.md

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.

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

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.

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.

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

@matifali @Kira-Pilot - if we were using this doc to assert how it should be, what would your list look like?

I don’t think the release phase should be tied to how we ship products. Early Access (EA) can be used with a flag for disruptive changes that alter existing behaviors. However, I prefer to ship additive features, such as Secrets or Pre-builds, without flags.

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.

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

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.

I want them to search first!

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.

I do want to use github discussions more

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.

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

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.

ooh yeah

alright. I'm going to change this and continue campaigning for a new section in Admin settings

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.

bpmct · 2025-07-01T13:47:12Z

I can review as soon as its marked "Ready for Review"

EdwardAngert · 2025-07-17T19:04:06Z

bump

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

github-actions bot added the stale This issue is like stale bread. label Jul 1, 2025

EdwardAngert removed the stale This issue is like stale bread. label Jul 1, 2025

edits from code review

7471dfc

EdwardAngert requested review from matifali and Kira-Pilot July 1, 2025 20:45

EdwardAngert added 2 commits July 1, 2025 20:51

make

e5f361c

Merge branch 'main' into coder-feature-stages

cabad4e

EdwardAngert marked this pull request as ready for review July 2, 2025 11:19

tweak features table

3e349d6

github-actions bot added the stale This issue is like stale bread. label Jul 15, 2025

EdwardAngert removed the stale This issue is like stale bread. label Jul 17, 2025

Kira-Pilot approved these changes Jul 17, 2025

View reviewed changes

	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

Uh oh!

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!

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!

EdwardAngert Jul 2, 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!

EdwardAngert Jul 1, 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!

Kira-Pilot commented Jun 23, 2025

Uh oh!

bpmct commented Jul 1, 2025

Uh oh!

EdwardAngert commented Jul 17, 2025

Uh oh!

Uh oh!

EdwardAngert commented Jun 17, 2025 •

edited

Loading

matifali Jun 18, 2025 •

edited

Loading

EdwardAngert Jul 2, 2025 •

edited

Loading

EdwardAngert Jul 1, 2025 •

edited

Loading