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.

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
wants to merge 5 commits into
base: main
Choose a base branch
from

Conversation

EdwardAngert
Copy link
Contributor

@EdwardAngert EdwardAngert commented Jun 17, 2025

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?

Summary by CodeRabbit

  • Documentation
    • Expanded and restructured the explanation of feature release stages.
    • Introduced new "Experiment (Hidden)" and "Legacy (Deprecated)" stages.
    • Updated Early Access and Beta stage descriptions with clearer guidance and support channels.
    • Improved clarity and consistency throughout the document.

@EdwardAngert EdwardAngert requested a review from bpmct June 17, 2025 20:17
@EdwardAngert EdwardAngert self-assigned this Jun 17, 2025
@EdwardAngert EdwardAngert added the docs Area: coder.com/docs label Jun 17, 2025
@EdwardAngert EdwardAngert requested review from matifali, Kira-Pilot, bpmct and stirby and removed request for bpmct June 17, 2025 20:26
Copy link
Member

@matifali matifali left a 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.

Comment on lines 16 to 18
| [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. |
Copy link
Member

@matifali matifali Jun 18, 2025

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


<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

Copy link
Contributor Author

@EdwardAngert EdwardAngert Jul 2, 2025

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?

Copy link
Member

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

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

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

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.

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 do want to use github discussions more

Comment on lines +141 to +142
## Legacy (Deprecated)

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.

| 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

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

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

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.

Copy link
Contributor Author

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

😭

@Kira-Pilot
Copy link
Member

Nice! Sorry for the delayed review.

@github-actions github-actions bot added the stale This issue is like stale bread. label Jul 1, 2025
@bpmct
Copy link
Member

bpmct commented Jul 1, 2025

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

@EdwardAngert EdwardAngert removed the stale This issue is like stale bread. label Jul 1, 2025
@EdwardAngert EdwardAngert marked this pull request as ready for review July 2, 2025 11:19
@github-actions github-actions bot added the stale This issue is like stale bread. label Jul 15, 2025
@EdwardAngert EdwardAngert removed the stale This issue is like stale bread. label Jul 17, 2025
@EdwardAngert
Copy link
Contributor Author

bump

@github-actions github-actions bot added the stale This issue is like stale bread. label Jul 25, 2025
Copy link

coderabbitai bot commented Jul 25, 2025

Walkthrough

The 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

File(s) Change Summary
docs/install/releases/feature-stages.md Expanded, restructured, and clarified feature release stage documentation; added new stages and details.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

A rabbit hopped through docs today,
Adding stages in a thoughtful way.
From hidden tests to legacy's end,
Each feature's journey now we comprehend.
With clearer words and stages anew,
The release path’s easy to hop through!
🐇✨

✨ Finishing Touches
🧪 Generate unit tests
  • Create PR with unit tests
  • Post copyable unit tests in a comment
  • Commit unit tests in branch coder-feature-stages

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

  • Review comments: Directly reply to a review comment made by CodeRabbit. Example:
    • I pushed a fix in commit <commit_id>, please review it.
    • Explain this complex logic.
    • Open a follow-up GitHub issue for this discussion.
  • Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
    • @coderabbitai explain this code block.
    • @coderabbitai modularize this function.
  • PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
    • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
    • @coderabbitai read src/utils.ts and explain its main purpose.
    • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
    • @coderabbitai help me debug CodeRabbit configuration file.

Support

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

  • @coderabbitai pause to pause the reviews on a PR.
  • @coderabbitai resume to resume the paused reviews.
  • @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
  • @coderabbitai full review to do a full review from scratch and review all the files again.
  • @coderabbitai summary to regenerate the summary of the PR.
  • @coderabbitai generate docstrings to generate docstrings for this PR.
  • @coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
  • @coderabbitai generate unit tests to generate unit tests for this PR.
  • @coderabbitai resolve resolve all the CodeRabbit review comments.
  • @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
  • @coderabbitai help to get help.

Other keywords and placeholders

  • Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
  • Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
  • Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

  • You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
  • Please see the configuration documentation for more information.
  • If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

  • Visit our Documentation for detailed information on how to use CodeRabbit.
  • Join our Discord Community to get help, request features, and share feedback.
  • Follow us on X/Twitter for updates and announcements.

Copy link

@coderabbitai coderabbitai bot left a 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 column

Missing 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

📥 Commits

Reviewing files that changed from the base of the PR and between d22ac1c and 3e349d6.

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

Comment on lines +126 to +128
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.

Copy link

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.

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

@github-actions github-actions bot removed the stale This issue is like stale bread. label Jul 26, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Area: coder.com/docs
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants