Improve feature flag documentation with feature flag label guidance#9794
Improve feature flag documentation with feature flag label guidance#9794Jalina2007 wants to merge 9 commits intowso2:masterfrom
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughReworks feature-flag docs to add label semantics (NEW, BETA, PREVIEW, COMING_SOON), separate flows for enabling/disabling vs. label-driven UI behavior, change Changes
🚥 Pre-merge checks | ✅ 6✅ Passed checks (6 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/FEATURE_FLAGS.md`:
- Line 126: Update the sentence in the docs to hyphenate the compound modifier:
change "disabledFeatures based approach" to "disabledFeatures-based approach" so
the phrase reads "In addition to the `enabled` and `disabledFeatures-based
approach` above, identity-apps also supports..." (ensure only the compound
modifier is hyphenated and surrounding punctuation/formatting remains
unchanged).
- Around line 143-166: The earlier example uses an invalid array form for the
features block ("features": [ ... ]) which conflicts with the correct object
form shown in the new example ("features": { ... }); update the earlier examples
that show "features": [ to instead use an object keyed by feature names (e.g.,
"organizations": { ... }) so the JSON becomes "features": { "organizations": {
... }, ... }, remove the array brackets and convert any array-entry key/value
pairs into standard object properties, and ensure trailing commas and
surrounding braces produce valid JSON consistent with the "users" example and
the documented schema.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yml
Review profile: CHILL
Plan: Pro
Run ID: 9c08d6b0-611f-4c0a-84c3-dea2f122b0e8
📒 Files selected for processing (1)
docs/FEATURE_FLAGS.md
Co-authored-by: Pavindu Lakshan <pavindulakshan@gmail.com>
Co-authored-by: Pavindu Lakshan <pavindulakshan@gmail.com>
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (1)
docs/FEATURE_FLAGS.md (1)
67-90:⚠️ Potential issue | 🟠 MajorFix the
featuresconfig shape inconsistency in examples.This example still uses
"features": [ ... ], while later examples and usage (state.config.ui.features?.users?.featureFlags) require an object map ("features": { ... }). The current snippet is structurally misleading for readers.📌 Proposed doc fix
{ "ui": { - "features": [ + "features": { // other features, "organizations": { "disabledFeatures": [ "organizations.filterByMetadataAttributes" ], "enabled": true, "featureFlags": [], "scopes": { "create": [ "internal_organization_create" ], "delete": [ "internal_organization_delete" ], "feature": [ "console:organizations" ], "read": [ "internal_organization_view" ], "update": [ "internal_organization_update" ] } }, - ] + } } }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/FEATURE_FLAGS.md` around lines 67 - 90, The example JSON uses "features": [ ... ] but the app expects a map/object for state.config.ui.features (e.g., features.users.featureFlags); update the snippet so "features" is an object (not an array) and make "organizations" a key in that object with the same nested fields (disabledFeatures, enabled, featureFlags, scopes) — i.e., replace the features array wrapper with an object/map containing "organizations": { ... } so the example shape matches runtime access like state.config.ui.features?.users?.featureFlags.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/FEATURE_FLAGS.md`:
- Around line 211-217: The docs list for `FeatureFlagLabel` is missing two
values; update the supported flag list in FEATURE_FLAGS.md to include
`EXPERIMENTAL` and `PREMIUM` to match the `FeatureStatusLabel` enum (which
contains NEW, BETA, EXPERIMENTAL, PREMIUM, COMING_SOON, PREVIEW), or
alternatively add a clear note that the doc intentionally documents only a
subset—ensure you reference the `FeatureStatusLabel` enum name and either add
the two missing enum values to the bullet list or add the explanatory sentence.
- Around line 193-197: The type annotation for exportButtonFlag is incorrect:
update the declaration that references useFeatureFlag (exportButtonFlag) to
match its actual return type (string | null) or remove the explicit type and let
TypeScript infer it; ensure any downstream usage (the JSX conditional) handles
the possible null case accordingly in the exportButtonFlag variable and related
render logic.
---
Duplicate comments:
In `@docs/FEATURE_FLAGS.md`:
- Around line 67-90: The example JSON uses "features": [ ... ] but the app
expects a map/object for state.config.ui.features (e.g.,
features.users.featureFlags); update the snippet so "features" is an object (not
an array) and make "organizations" a key in that object with the same nested
fields (disabledFeatures, enabled, featureFlags, scopes) — i.e., replace the
features array wrapper with an object/map containing "organizations": { ... } so
the example shape matches runtime access like
state.config.ui.features?.users?.featureFlags.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yml
Review profile: CHILL
Plan: Pro
Run ID: 4666a044-8c41-4e30-822e-efae49955854
📒 Files selected for processing (1)
docs/FEATURE_FLAGS.md
Removed the conclusion section about feature flags.
There was a problem hiding this comment.
♻️ Duplicate comments (1)
docs/FEATURE_FLAGS.md (1)
67-90:⚠️ Potential issue | 🟠 MajorUse object form for
featuresin this example too.At Line 70, this sample still uses
"features": [ ... ]while other updated samples use"features": { ... }. This is inconsistent and the keyed entry style shown inside the array is not valid JSON structure for this schema.Suggested fix
{ "ui": { - "features": [ + "features": { // other features, "organizations": { "disabledFeatures": [ "organizations.filterByMetadataAttributes" ], "enabled": true, "featureFlags": [], "scopes": { "create": [ "internal_organization_create" ], "delete": [ "internal_organization_delete" ], "feature": [ "console:organizations" ], "read": [ "internal_organization_view" ], "update": [ "internal_organization_update" ] } }, - ] + } } }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/FEATURE_FLAGS.md` around lines 67 - 90, The example uses "features": [ ... ] with a keyed "organizations" entry inside an array which is invalid; change the sample to use the object form ("features": { ... }) and make "organizations" a property name mapping to its configuration object (preserve keys like "disabledFeatures", "enabled", "featureFlags", and "scopes" with entries "create", "delete", "feature", "read", "update") so the JSON is valid and consistent with other examples.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In `@docs/FEATURE_FLAGS.md`:
- Around line 67-90: The example uses "features": [ ... ] with a keyed
"organizations" entry inside an array which is invalid; change the sample to use
the object form ("features": { ... }) and make "organizations" a property name
mapping to its configuration object (preserve keys like "disabledFeatures",
"enabled", "featureFlags", and "scopes" with entries "create", "delete",
"feature", "read", "update") so the JSON is valid and consistent with other
examples.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yml
Review profile: CHILL
Plan: Pro
Run ID: 041d0f48-0b0b-4ce6-859a-15a997784d65
📒 Files selected for processing (1)
docs/FEATURE_FLAGS.md
|
Hi, just checking in. Is there any other changes that I should make? |
| Feature flags are a powerful way to enable, disable and label features in your application dynamically. This approach allows you to | ||
| deploy new features safely, perform A/B testing, and roll out features incrementally. In this guide, we'll walk through how to | ||
| define and use feature flags in identity-apps React applications. | ||
|
|
There was a problem hiding this comment.
This "high level imformation" section no longer fits here with the introduction of using feature flags show feature status, IMO. Let's remove that section altogether.
There was a problem hiding this comment.
And let's put shortcut links to navigate to the two main sections, conditionally enabling feature and configuring feature status labels, instead.
|
|
||
| return ( | ||
| <Button> | ||
| { exportButtonFlag === "NEW" ? "Export Users [New]" : "Export Users" } |
There was a problem hiding this comment.
This example, updating just the button text based on feature status, doesn't look good, IMO. Shall we find a better example from the codebase?
| `organizations.filterByMetadataAttributes` is included in the `disabledFeatures` array, the section will not be displayed. | ||
|
|
||
| ## Conclusion | ||
| ## Changing UI Behaviour Using Feature Labels |
There was a problem hiding this comment.
Let's also add another section for defining nested features with their own scopes (eg: https://github.com/wso2/identity-apps/blob/master/apps/console/src/public/deployment.config.json#L580).
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/FEATURE_FLAGS.md (1)
67-91:⚠️ Potential issue | 🔴 CriticalFix: Array syntax still present despite previous review.
This deployment config example still uses invalid array syntax
"features": [on line 70, which conflicts with the correct object syntax shown in lines 34-55 and 142-167. This was flagged in previous reviews and marked as addressed, but the issue remains.The syntax
"features": [ "organizations": { ... } ]is invalid JSON—you cannot have key-value pairs directly inside an array.🔧 Required fix
{ "ui": { - "features": [ + "features": { // other features, "organizations": { "disabledFeatures": [ "organizations.filterByMetadataAttributes" ], "enabled": true, "featureFlags": [], "scopes": { "create": [ "internal_organization_create" ], "delete": [ "internal_organization_delete" ], "feature": [ "console:organizations" ], "read": [ "internal_organization_view" ], "update": [ "internal_organization_update" ] } }, - ] + } } }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/FEATURE_FLAGS.md` around lines 67 - 91, The example JSON uses invalid array syntax for the "features" key (it currently shows "features": [ ... ] with a direct "organizations": { ... } entry); change "features" to be an object mapping instead (i.e., "features": { "organizations": { ... } }) so "organizations" becomes a property rather than an array element, and ensure the surrounding JSON structure and commas are valid; update the example around the "features" and "organizations" entries to match the object-based examples earlier (referencing the "features" key and the "organizations" object).
♻️ Duplicate comments (1)
docs/FEATURE_FLAGS.md (1)
211-217:⚠️ Potential issue | 🟡 MinorAdd missing
EXPERIMENTALandPREMIUMvalues to the supported flags list.The documentation lists only four values (
NEW,BETA,COMING_SOON,PREVIEW), but the actualFeatureStatusLabelenum implementation includesEXPERIMENTALandPREMIUMas well.📝 Proposed fix
`FeatureFlagLabel` currently supports the following flag values: - `NEW` - `BETA` +- `EXPERIMENTAL` +- `PREMIUM` - `COMING_SOON` - `PREVIEW`🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/FEATURE_FLAGS.md` around lines 211 - 217, The docs list for supported flags is missing two enum values; update the `FeatureFlagLabel`/`FeatureStatusLabel` supported flags list to include `EXPERIMENTAL` and `PREMIUM` so it matches the `FeatureStatusLabel` enum implementation, adding those two entries alongside `NEW`, `BETA`, `COMING_SOON`, and `PREVIEW`.
🧹 Nitpick comments (3)
docs/FEATURE_FLAGS.md (3)
124-124: Consider adding a section on nested features with their own scopes.As requested in previous review comments, adding documentation for defining nested features with their own scopes (e.g., as shown in the actual
deployment.config.json) would make this guide more comprehensive. This could be added as a subsection under "Conditionally Enabling/Disabling Features" or as a separate advanced section.Would you like me to help draft an example section covering nested feature configurations?
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/FEATURE_FLAGS.md` at line 124, Add a new subsection under "Conditionally Enabling/Disabling Features" (or as an "Advanced: Nested Features" section) that documents how to define nested feature flags with their own scopes, referencing the actual deployment.config.json structure used in the repo; show the nested keys, scope fields, and precedence rules (e.g., parent vs child feature evaluation) and include a minimal example mirroring the deployment.config.json naming and fields so readers can map docs to the real config.
180-203: Consider a more realistic example from the codebase.While this example correctly demonstrates
useFeatureFlagusage with proper type annotation, the use case of modifying button text based on a status flag is somewhat contrived. As noted in previous review comments, a real-world example from the actual codebase might better illustrate typical usage patterns and provide more practical guidance.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/FEATURE_FLAGS.md` around lines 180 - 203, Replace the contrived Button-text example in the App component with a more realistic codebase use-case: fetch the feature flags from userFeatureFlags (state.config.ui.features?.users?.featureFlags) and use useFeatureFlag to toggle rendering of a real UI behavior (for example, conditionally render an InviteUserModal component or enable an enhanced UsersTable column) instead of merely changing button text; update the exportButtonFlag usage to reflect the real flag name and expected enum values, and demonstrate both branch rendering and a fallback (e.g., render legacy component when flag !== "NEW") so reviewers can see how App, userFeatureFlags, useFeatureFlag, and exportButtonFlag are applied in a practical scenario.
7-15: Consider restructuring the high-level overview section.As noted in previous review comments, this section might not fit well with the new two-part structure (enabling/disabling vs. feature labels). Consider replacing it with shortcut links to the two main sections for easier navigation:
## Quick Navigation - [Conditionally Enabling/Disabling Features](`#conditionally-enablingdisabling-features`) - [Changing UI Behaviour Using Feature Labels](`#changing-ui-behaviour-using-feature-labels`)This would help readers quickly jump to the section most relevant to their needs.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/FEATURE_FLAGS.md` around lines 7 - 15, Replace the "High-Level Overview" section with a concise "Quick Navigation" block linking to the two main sections so readers can jump directly to what they need; specifically remove the existing High-Level Overview bullet list and add shortcut links to the "Conditionally Enabling/Disabling Features" section and the "Changing UI Behaviour Using Feature Labels" section (referencing the `disabledFeatures` array guidance and the `featureFlags` array guidance) so users can quickly navigate to enabling/disabling instructions and feature label behavior.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Outside diff comments:
In `@docs/FEATURE_FLAGS.md`:
- Around line 67-91: The example JSON uses invalid array syntax for the
"features" key (it currently shows "features": [ ... ] with a direct
"organizations": { ... } entry); change "features" to be an object mapping
instead (i.e., "features": { "organizations": { ... } }) so "organizations"
becomes a property rather than an array element, and ensure the surrounding JSON
structure and commas are valid; update the example around the "features" and
"organizations" entries to match the object-based examples earlier (referencing
the "features" key and the "organizations" object).
---
Duplicate comments:
In `@docs/FEATURE_FLAGS.md`:
- Around line 211-217: The docs list for supported flags is missing two enum
values; update the `FeatureFlagLabel`/`FeatureStatusLabel` supported flags list
to include `EXPERIMENTAL` and `PREMIUM` so it matches the `FeatureStatusLabel`
enum implementation, adding those two entries alongside `NEW`, `BETA`,
`COMING_SOON`, and `PREVIEW`.
---
Nitpick comments:
In `@docs/FEATURE_FLAGS.md`:
- Line 124: Add a new subsection under "Conditionally Enabling/Disabling
Features" (or as an "Advanced: Nested Features" section) that documents how to
define nested feature flags with their own scopes, referencing the actual
deployment.config.json structure used in the repo; show the nested keys, scope
fields, and precedence rules (e.g., parent vs child feature evaluation) and
include a minimal example mirroring the deployment.config.json naming and fields
so readers can map docs to the real config.
- Around line 180-203: Replace the contrived Button-text example in the App
component with a more realistic codebase use-case: fetch the feature flags from
userFeatureFlags (state.config.ui.features?.users?.featureFlags) and use
useFeatureFlag to toggle rendering of a real UI behavior (for example,
conditionally render an InviteUserModal component or enable an enhanced
UsersTable column) instead of merely changing button text; update the
exportButtonFlag usage to reflect the real flag name and expected enum values,
and demonstrate both branch rendering and a fallback (e.g., render legacy
component when flag !== "NEW") so reviewers can see how App, userFeatureFlags,
useFeatureFlag, and exportButtonFlag are applied in a practical scenario.
- Around line 7-15: Replace the "High-Level Overview" section with a concise
"Quick Navigation" block linking to the two main sections so readers can jump
directly to what they need; specifically remove the existing High-Level Overview
bullet list and add shortcut links to the "Conditionally Enabling/Disabling
Features" section and the "Changing UI Behaviour Using Feature Labels" section
(referencing the `disabledFeatures` array guidance and the `featureFlags` array
guidance) so users can quickly navigate to enabling/disabling instructions and
feature label behavior.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yml
Review profile: CHILL
Plan: Pro
Run ID: f163cdd1-9c26-476a-83ca-f1dd03aab00d
📒 Files selected for processing (1)
docs/FEATURE_FLAGS.md
2 participants
Purpose
Improve the feature flags documentation by adding guidance for label-based feature flags alongside the existing enable/disable flow. This update clarifies how to use featureFlags, useFeatureFlag, and FeatureFlagLabel for UI behavior and status labels such as New, Beta, and Preview.
Related Issues
fixes wso2/product-is#26866
Related PRs
Checklist
Security checks
Developer Checklist (Mandatory)
product-isissue to track any behavioral change or migration impact.