-
Notifications
You must be signed in to change notification settings - Fork 952
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.
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
base: main
Are you sure you want to change the base?
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Left a few comments and queries.
| [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. | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We should mention Discord, GitHub, and Documentation as support channels for GA features, at least for the OSS community.
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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).
There was a problem hiding this comment.
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.
|
||
<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: |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@matifali @Kira-Pilot - if we were using this doc to assert how it should be, what would your list look like?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
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. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[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. |
There was a problem hiding this comment.
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!
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). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Why are we asking for feedback on the internal repo? We should use the coder/coder repo issues or GitHub Discussions.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I do want to use github discussions more
## Legacy (Deprecated) | ||
|
There was a problem hiding this comment.
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.
| 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. | |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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
|-------------------------------------------|--------|------------------|-----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ||
| [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. | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Another product question: will all beta
features be opt-in? Or will some just be tagged beta
?
What if something is greenfield?
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Are they? Above we say they're opt-in.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
ooh yeah
alright. I'm going to change this and continue campaigning for a new section in Admin settings
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). |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
😭
Nice! Sorry for the delayed review. |
I can review as soon as its marked "Ready for Review" |
bump |
WalkthroughThe documentation for Coder's feature release stages was expanded and reorganized. New stages "Experiment (Hidden)" and "Legacy (Deprecated)" were introduced, and existing stage descriptions were clarified and updated. Additional details on support channels, feature stability, and documentation sources were incorporated throughout the document. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Poem
✨ Finishing Touches🧪 Generate unit tests
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Actionable comments posted: 1
🧹 Nitpick comments (5)
docs/install/releases/feature-stages.md (5)
13-18
: Clarify wording & punctuation in Support columnMissing delimiters make the Support cells hard to scan. Adding commas keeps the style consistent with subsequent prose.
-| [Early Access](#early-access-features) | No | No | Limited documentation GitHub issues | For staging only. Functional, but not feature-complete or stable. Disabled by default. +| [Early Access](#early-access-features) | No | No | Limited documentation, GitHub issues | For staging only. Functional, but not feature-complete or stable. Disabled by default. -| [Beta](#beta) | No | Not fully | Documentation Discord GitHub | Publicly available on an opt-in basis. In active development with minor bugs. Suitable for staging; may be acceptable for some production deployments. +| [Beta](#beta) | No | Not fully | Documentation, Discord, GitHub | Publicly available on an opt-in basis. In active development with minor bugs. Suitable for staging; may be acceptable for some production deployments.
19-19
: Remove superfluous “of”-…updated outside of the limits defined… +…updated outside the limits defined…
27-30
: Tighten wording & fix awkward phrasing-They are not ready for ongoing use and aspects might be broken or can lead to data loss. +They are not ready for ongoing use; components may be broken and could 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. +You can enable an experimental feature to explore the latest Coder code or contribute fixes.
110-113
: Singular form for “issue”-…or create a [GitHub issues](https://github.com/coder/coder/issues) if there isn't one already. +…or create a [GitHub issue](https://github.com/coder/coder/issues) if there isn't one already.
149-151
: Grammar & conciseness fixes in Legacy section-On rare occasions, the Coder team may deprecate features that have been replaced by another functionality, or that tedious to maintain. +On rare occasions, the Coder team may deprecate features that have been replaced by alternative functionality or that are 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. +To maintain stability and predictability, we avoid deprecating features that might lead to breaking changes whenever possible.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/install/releases/feature-stages.md
(3 hunks)
🧰 Additional context used
🧠 Learnings (1)
docs/install/releases/feature-stages.md (2)
Learnt from: ThomasK33
PR: #18809
File: coderd/apidoc/swagger.json:2160-2186
Timestamp: 2025-07-21T14:30:40.647Z
Learning: For the Coder repository, API specification or standards compliance issues should be raised in the Go source files (e.g., handler annotations or swaggo comments), not in auto-generated files like coderd/apidoc/swagger.json.
Learnt from: ThomasK33
PR: #18809
File: docs/reference/api/enterprise.md:1418-1424
Timestamp: 2025-07-21T17:42:55.831Z
Learning: For the Coder repository, API specification or standards compliance issues should be raised in the Go source files (e.g., handler annotations or swaggo comments), not in auto-generated files like docs/reference/api/enterprise.md.
🪛 LanguageTool
docs/install/releases/feature-stages.md
[style] ~19-~19: This phrase is redundant. Consider using “outside”.
Context: ...ue to function, but will not be updated outside of the limits defined in a customer's lice...
(OUTSIDE_OF)
[style] ~30-~30: Consider using an alternative to strengthen your wording.
Context: ...experimental feature for testing if you want to explore the latest Coder code or if ...
(WANT_KEEN)
[style] ~150-~150: Consider a more concise word here.
Context: ...ionality, or that tedious to maintain. In order to maintain stability and predictability, ...
(IN_ORDER_TO_PREMIUM)
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. | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🛠️ Refactor suggestion
Explicitly exclude Experiment from GA definition
Without this, hidden experiments are implicitly GA.
-All features that are not explicitly tagged as `Early access` or `Beta` are considered generally available (GA).
+All features that are not explicitly tagged as `Experiment`, `Early access`, or `Beta` are considered generally available (GA).
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
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 `Experiment`, `Early access`, or `Beta` are considered generally available (GA). | |
They have been tested, are stable, and are enabled by default. |
🤖 Prompt for AI Agents
In docs/install/releases/feature-stages.md around lines 126 to 128, explicitly
exclude features tagged as "Experiment" from being considered generally
available (GA). Update the definition or description to clarify that only
features not tagged as Early access, Beta, or Experiment are GA, ensuring hidden
experiments are not implicitly treated as GA.
| [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. Hidden and disabled by default. | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| [Experiment](#experiment-hidden) | No | No | N/A | For staging and testing only. Not feature-complete or stable. Hidden and disabled by default. | | |
| [Experiment](#experiment-hidden) | No | No | GitHub | For staging and testing only. Not feature-complete or stable. Hidden and disabled by default. | |
I think we should support engaging through GitHub for experimental features. It is very important to get feedback at an early stage.
Summary
Edit the feature stages doc to define and clarify each stage both for Coder users and internally.
Specifically:
in pr/in progress
todo
help wanted
Summary by CodeRabbit