feat(docs): allow for server side feature flags (#5627)

fern-api · Jan 16, 2025 · 813276c · 813276c
1 parent 06aad51
commit 813276c
Show file tree

Hide file tree

Showing 55 changed files with 628 additions and 148 deletions.
diff --git a/docs-yml.schema.json b/docs-yml.schema.json
@@ -551,6 +551,71 @@
         }
       ]
     },
+    "docs.FeatureFlag": {
+      "type": "object",
+      "properties": {
+        "flag": {
+          "type": "string"
+        },
+        "fallback-value": {
+          "oneOf": [
+            {
+              "type": [
+                "string",
+                "number",
+                "boolean",
+                "object",
+                "array",
+                "null"
+              ]
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "match": {
+          "oneOf": [
+            {
+              "type": [
+                "string",
+                "number",
+                "boolean",
+                "object",
+                "array",
+                "null"
+              ]
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "required": [
+        "flag"
+      ],
+      "additionalProperties": false
+    },
+    "docs.FeatureFlagConfiguration": {
+      "anyOf": [
+        {
+          "type": "string",
+          "description": "The name of the feature flag, We assume that it is a boolean feature flag that needs to be evaluated to true."
+        },
+        {
+          "$ref": "#/definitions/docs.FeatureFlag",
+          "description": "A single feature flag with a configurable name, fallback value, and match value. Especially useful for non boolean feature flags."
+        },
+        {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/docs.FeatureFlag"
+          },
+          "description": "A list of feature flags. If any of the feature flags are satisifed, we will show all content."
+        }
+      ]
+    },
     "docs.ChangelogFolderRelativePath": {
       "type": "string"
     },
@@ -577,6 +642,16 @@
             }
           ]
         },
+        "feature-flag": {
+          "oneOf": [
+            {
+              "$ref": "#/definitions/docs.FeatureFlagConfiguration"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
         "display-name": {
           "type": "string"
         },
@@ -678,6 +753,16 @@
             }
           ]
         },
+        "feature-flag": {
+          "oneOf": [
+            {
+              "$ref": "#/definitions/docs.FeatureFlagConfiguration"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
         "display-name": {
           "type": "string"
         },
@@ -734,6 +819,16 @@
             }
           ]
         },
+        "feature-flag": {
+          "oneOf": [
+            {
+              "$ref": "#/definitions/docs.FeatureFlagConfiguration"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
         "page": {
           "type": "string"
         },
@@ -800,6 +895,16 @@
             }
           ]
         },
+        "feature-flag": {
+          "oneOf": [
+            {
+              "$ref": "#/definitions/docs.FeatureFlagConfiguration"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
         "section": {
           "type": "string"
         },
@@ -1049,6 +1154,16 @@
             }
           ]
         },
+        "feature-flag": {
+          "oneOf": [
+            {
+              "$ref": "#/definitions/docs.FeatureFlagConfiguration"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
         "title": {
           "oneOf": [
             {
@@ -1171,6 +1286,16 @@
             }
           ]
         },
+        "feature-flag": {
+          "oneOf": [
+            {
+              "$ref": "#/definitions/docs.FeatureFlagConfiguration"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
         "section": {
           "type": "string"
         },
@@ -1289,6 +1414,16 @@
             }
           ]
         },
+        "feature-flag": {
+          "oneOf": [
+            {
+              "$ref": "#/definitions/docs.FeatureFlagConfiguration"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
         "endpoint": {
           "type": "string"
         },
@@ -1424,6 +1559,16 @@
             }
           ]
         },
+        "feature-flag": {
+          "oneOf": [
+            {
+              "$ref": "#/definitions/docs.FeatureFlagConfiguration"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
         "api": {
           "type": "string"
         },
@@ -1612,6 +1757,16 @@
             }
           ]
         },
+        "feature-flag": {
+          "oneOf": [
+            {
+              "$ref": "#/definitions/docs.FeatureFlagConfiguration"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
         "changelog": {
           "$ref": "#/definitions/docs.ChangelogFolderRelativePath"
         },

diff --git a/fern/apis/docs-yml/definition/docs.yml b/fern/apis/docs-yml/definition/docs.yml
@@ -161,7 +161,7 @@ types:
   TabId: string
 
   TabConfig:
-    extends: WithPermissions
+    extends: [WithPermissions, WithFeatureFlags]
     properties:
       display-name: string
       icon: optional<string>
@@ -230,7 +230,7 @@ types:
 
 
   VersionConfig:
-    extends: WithPermissions
+    extends: [WithPermissions, WithFeatureFlags]
     properties:
       display-name: string
       path:
@@ -450,6 +450,32 @@ types:
       orphaned:
         type: optional<boolean>
         docs: When `orphaned` is set to `true`, the roles will not inherit from parents.
+
+  FeatureFlag:
+    properties:
+      flag:
+        type: string
+        docs: The name of the feature flag to check.
+      fallback-value:
+        type: optional<unknown>
+        docs: The default value to use if the feature flag is not set. If not specified, defaults to false.
+      match:
+        type: optional<unknown>
+        docs: The value that the feature flag should match for the content to be shown. If not specified, content is shown when the flag is true.
+
+  FeatureFlagConfiguration:
+    discriminated: false
+    union: 
+      - type: string
+        docs: The name of the feature flag, We assume that it is a boolean feature flag that needs to be evaluated to true. 
+      - type: FeatureFlag
+        docs: A single feature flag with a configurable name, fallback value, and match value. Especially useful for non boolean feature flags. 
+      - type: list<FeatureFlag>
+        docs: A list of feature flags. If any of the feature flags are satisifed, we will show all content. 
+
+  WithFeatureFlags:
+    properties:
+      feature-flag: optional<FeatureFlagConfiguration>
 
   FontConfig:
     properties:
@@ -527,7 +553,7 @@ types:
           @default: `normal`.
 
   PageConfiguration:
-    extends: WithPermissions
+    extends: [WithPermissions, WithFeatureFlags]
     properties:
       page: string
       path: string
@@ -536,7 +562,7 @@ types:
       hidden: optional<boolean>
 
   ChangelogConfiguration:
-    extends: WithPermissions
+    extends: [WithPermissions, WithFeatureFlags]
     properties:
       changelog: ChangelogFolderRelativePath
       title: optional<string> # defaults to "Changelog"
@@ -546,7 +572,7 @@ types:
       # skip-slug: optional<boolean> # skip-slug is not needed for changelog
 
   SectionConfiguration:
-    extends: WithPermissions
+    extends: [WithPermissions, WithFeatureFlags]
     properties:
       section: string
       path:
@@ -561,7 +587,7 @@ types:
       skip-slug: optional<boolean>
 
   ApiReferenceConfiguration:
-    extends: WithPermissions
+    extends: [WithPermissions, WithFeatureFlags]
     properties:
       api: string
       "api-name":
@@ -621,7 +647,7 @@ types:
       - LinkConfiguration
 
   ApiReferenceSectionConfiguration:
-    extends: WithPermissions
+    extends: [WithPermissions, WithFeatureFlags]
     properties:
       section:
         type: string
@@ -649,7 +675,7 @@ types:
       - ApiReferencePackageConfigurationWithOptions
 
   ApiReferencePackageConfigurationWithOptions:
-    extends: WithPermissions
+    extends: [WithPermissions, WithFeatureFlags]
     properties:
       title: optional<string>
       summary:
@@ -666,7 +692,7 @@ types:
         docs: Settings for the api playground that is applied only to descendants of this api package.
 
   ApiReferenceEndpointConfiguration:
-    extends: WithPermissions
+    extends: [WithPermissions, WithFeatureFlags]
     properties:
       endpoint: string
       title: optional<string>

diff --git a/fern/pages/changelogs/cli/2025-01-16.mdx b/fern/pages/changelogs/cli/2025-01-16.mdx
@@ -0,0 +1,24 @@
+## 0.50.4
+**`(internal):`** The docs.yml now supports a separate configurtation for `feature-flags` which allows Fern to render 
+pieces of content depending on whether or not certain feature flags are enabled for particular user. 
+
+This feature is in alpha stage; please contact [email protected] to learn more!
+
+```yml docs.yml
+navigation:
+  - page: Page 1
+    feature-flag: my-feature-flag-a # single boolean flag
+  - page: Page 2
+    feature: # multiple boolean flags
+      - flag: my-feature-flag-a
+      - flag: my-feature-flag-b
+  - section: Section Title
+    viewers: role-a
+    feature-flag: # configurable match
+      flag: my-feature-flag-a
+      fallback-value: "ga"
+      match: "beta"
+    layout: []
+```
+
+
diff --git a/...ages/changelogs/ts-express/2025-01-15.mdx → ...ages/changelogs/ts-express/2025-01-16.mdx b/...ages/changelogs/ts-express/2025-01-15.mdx → ...ages/changelogs/ts-express/2025-01-16.mdx
diff --git a/packages/cli/cli/versions.yml b/packages/cli/cli/versions.yml
@@ -1,3 +1,30 @@
+- changelogEntry:
+    - summary: |
+        The docs.yml now supports a separate configurtation for `feature-flags` which allows Fern to render 
+        pieces of content depending on whether or not certain feature flags are enabled for particular user. 
+
+        This feature is in alpha stage; please contact [email protected] to learn more!
+
+        ```yml docs.yml
+        navigation:
+          - page: Page 1
+            feature-flag: my-feature-flag-a # single boolean flag
+          - page: Page 2
+            feature: # multiple boolean flags
+              - flag: my-feature-flag-a
+              - flag: my-feature-flag-b
+          - section: Section Title
+            viewers: role-a
+            feature-flag: # configurable match
+              flag: my-feature-flag-a
+              fallback-value: "ga"
+              match: "beta"
+            layout: []
+        ```
+      type: internal
+  irVersion: 55
+  version: 0.50.4
+
 - changelogEntry:
     - summary: |
         Fixes an issue where optional, nullable properties resulted in a double optional in the