Update documentation for feature stages and availability

bpmct · bpmct · commit 5c03ec59fa27 · 2024-10-04T22:59:46.000Z
Refine stages to better explain Alpha, Beta, and GA availability. Include guidance for feature usage and opt-in recommendations for early access and experimental stages to ensure proper understanding of development phases.
diff --git a/docs/contributing/feature-stages.md b/docs/contributing/feature-stages.md
@@ -1,21 +1,34 @@
 # Feature stages
 
-Some Coder features are released as Alpha or Experimental.
+Some Coder features are released in feature stages before they are generally
+available.
 
-## Alpha features
+If you encounter an issue with any Coder feature, please submit a
+[GitHub issues](https://github.com/coder/coder/issues) or join the
+[Coder Discord](https://discord.gg/coder).
 
-Alpha features are enabled in all Coder deployments but the feature is subject
-to change, or even be removed. Breaking changes may not be documented in the
-changelog. In most cases, features will only stay in alpha for 1 month.
+## Early access features
 
-We recommend using [GitHub issues](https://github.com/coder/coder/issues) to
-leave feedback and get support for alpha features.
+Early access features are neither feature-complete nor stable. We do not
+recommend using early access features in production deployments.
+
+Coder releases early access features behind an “unsafe” experiment, where
+they’re accessible but not easy to find.
 
 ## Experimental features
 
 These features are disabled by default, and not recommended for use in
 production as they may cause performance or stability issues. In most cases,
-features will only stay in experimental for 1-2 weeks of internal testing.
+experimental features are complete, but require further internal testing and
+will stay in the experimental stage for one month.
+
+Coder may make significant changes to experiments or revert features to a
+feature flag at any time.
+
+If you plan to activate an experimental feature, we suggest that you use a
+staging deployment.
+
+You can opt-out of an experiment after you've enabled it.
 
 ```yaml
 # Enable all experimental features
@@ -27,7 +40,7 @@ coder server --experiments=feature1,feature2
 # Alternatively, use the `CODER_EXPERIMENTS` environment variable.
 ```
 
-## Available experimental features
+### Available experimental features
 
 <!-- Code generated by scripts/release/docs_update_experiments.sh. DO NOT EDIT. -->
 <!-- BEGIN: available-experimental-features -->
@@ -37,3 +50,14 @@ coder server --experiments=feature1,feature2
 | `notifications` | Sends notifications via SMTP and webhooks following certain events. | stable       |
 
 <!-- END: available-experimental-features -->
+
+## Beta
+
+Beta features are open to the public, but are tagged with a `Beta` label.
+
+They’re subject to minor changes and may contain bugs, but are generally ready
+for use.
+
+## General Availability (GA)
+
+All other features have been tested, are stable, and are enabled by default.
