- Notifications
You must be signed in to change notification settings - Fork925
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 ourterms of service andprivacy 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.
| | [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 do not need to repeat support in the Description column, since we already have a separate Support column.
| | [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 aredisabled by default. | |
| Coder sometimes releases early access features that are available for use, but areopt-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.
| <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.
| 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.
| 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. |
| 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.
| ## 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 releaseearly-access andexperimental 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.
| |-------------------------------------------|--------|------------------|-----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ||
| | [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 allbeta features be opt-in? Or will some just be taggedbeta?
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? Abovewe say they're opt-in.
| 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.
Nice! Sorry for the delayed review. |
Uh oh!
There was an error while loading.Please reload this page.
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