From e074117f6fdf09a130f63b1cb2eec951739b72bd Mon Sep 17 00:00:00 2001
From: Tatiana Inama <tatiana@lightdash.com>
Date: Thu, 26 Jun 2025 16:31:13 +0200
Subject: [PATCH] docs: Define feature maturity levels

---
 docs.json                              | 13 ++-----
 references/feature-maturity-levels.mdx | 54 ++++++++++++++++++++++++++
 references/references.mdx              |  4 ++
 3 files changed, 62 insertions(+), 9 deletions(-)
 create mode 100644 references/feature-maturity-levels.mdx

diff --git a/docs.json b/docs.json
index ad88c5d..8a078ea 100644
--- a/docs.json
+++ b/docs.json
@@ -196,18 +196,13 @@
               },
               {
                 "group": "User",
-                "pages": [
-                  "references/user",
-                  "references/personal_tokens"
-                ]
+                "pages": ["references/user", "references/personal_tokens"]
               },
               {
                 "group": "Embedding",
-                "pages": [
-                  "references/embedding",
-                  "references/react-sdk"
-                ]
-              }
+                "pages": ["references/embedding", "references/react-sdk"]
+              },
+              "references/feature-maturity-levels"
             ]
           },
           {
diff --git a/references/feature-maturity-levels.mdx b/references/feature-maturity-levels.mdx
new file mode 100644
index 0000000..77fa37f
--- /dev/null
+++ b/references/feature-maturity-levels.mdx
@@ -0,0 +1,54 @@
+---
+title: "Feature Maturity Levels"
+description: "We use standardized maturity levels to help you understand the stability and availability of features as we develop them"
+sidebarTitle: "Feature Maturity Levels"
+---
+
+## Feature lifecycle
+
+```mermaid
+flowchart LR
+    A(Experimental) --> B("Early Access")
+    B --> C("Generally Available (GA)")
+    
+    style A fill:#99F4D1,stroke:#99F4D1,color:#000
+    style B fill:#D6C1FA,stroke:#D6C1FA,color:#000
+    style C fill:#7262FF,stroke:#D6C1FA,color:#fff
+
+    linkStyle 0,1 stroke:#c0c0c0,stroke-with:1px
+```
+
+### Experimental
+
+Experimental features are where we explore new ideas and test out proof of concepts.
+
+- We're still building out core functionality, so things may be incomplete or unstable
+- We might make breaking changes without much notice as we iterate
+- We limit access to our internal team and design partners
+- Our design partners help us figure out what the feature should do and how it should work
+- We're in full feedback-driven development mode
+
+### Early Access
+
+Early Access features are stable and work well, but we're still actively testing and improving them based on your feedback.
+
+- Work smoothly with good performance
+- We might still make some changes based on what you tell us
+- We provide comprehensive documentation
+- Breaking changes are rare, and we'll always give you plenty of notice
+- Our support team is ready to help
+- We might put some usage limits in place while we fine-tune things
+- We're getting these features ready for our full GA release
+
+### Generally Available (GA)
+
+GA features are production-ready and fully supported by our team.
+
+- We provide complete documentation and training materials
+- These features are stable with our commitment to backward compatibility
+
+## Using Feature Maturity Levels
+
+These levels help you understand what to expect from each feature's stability and performance, so you can decide what works best for your production environment and risk tolerance.
+
+When you're evaluating features for your use case, we recommend considering the maturity level alongside your requirements for stability, support, and backward compatibility.
\ No newline at end of file
diff --git a/references/references.mdx b/references/references.mdx
index 41a9359..7895b5a 100644
--- a/references/references.mdx
+++ b/references/references.mdx
@@ -48,4 +48,8 @@ mode: wide
   <Card title="SCIM Integration" href="/references/scim-integration" icon="file-lines" iconType="solid" horizontal>
   SCIM Integration is only available on...
   </Card>
+  
+  <Card title="Feature Maturity Levels" href="/references/feature-maturity-levels" icon="file-lines" iconType="solid" horizontal>
+    Standardized levels that communicate...
+  </Card>
 </CardGroup>