Skip to content

docs(Flag Dependency): Add documentation around feature prerequisites #8795

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.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
emyller wants to merge 1 commit into
base: main
Choose a base branch
from
+45 −0
Open

docs(Flag Dependency): Add documentation around feature prerequisites #8795

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 45 additions & 0 deletions docs/docs/managing-flags/flag-dependencies.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
---
title: Flag Dependencies
sidebar_label: Flag Dependencies
sidebar_position: 20
---

## Overview

Suppose you have a feature flag `coffee_machine`, but it needs another feature `hamster_power_grid` turned on so it can be evaluated as enabled. Flag dependencies allow for establishing prerequisites between flags.

![`coffee_machine` requires `hamster_power_grid`](/img/flag-dependencies/overview.png)
Comment thread
coderabbitai[bot] marked this conversation as resolved.

:::info Available in all plans

Flag dependencies are free and included in all plans.

:::
Comment on lines +12 to +17

@khvn26 khvn26 Oct 16, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's not break the pattern for other docs (imply free, specify plan gates)

Suggested change
:::info Available in all plans
Flag dependencies are free and included in all plans.
:::


When the prerequisite feature is disabled, the dependent feature is also evaluated as _disabled_. By default, a feature prerequisite takes priority over segment overrides, but you can move overrides in the _Segment Overrides_ tab to adjust if necessary. As usual, identity overrides always take precedence.

@khvn26 khvn26 Oct 16, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unfortunately during testing I've found that, before #8656 is done, we're not quite ready to do that. The system segment priorities will be fixed until then.

Also, added some behaviour details that users might be interested in.

Suggested change
When the prerequisite feature is disabled, the dependent feature is also evaluated as _disabled_. By default, a feature prerequisite takes priority over segment overrides, but you can move overrides in the _Segment Overrides_ tab to adjust if necessary. As usual, identity overrides always take precedence.
When the prerequisite feature is disabled, the dependent feature is also evaluated as _disabled_. Flag value will be served from the environment default.
Feature prerequisites take priority over segment overrides. Identity overrides still take absolute precedence. Prerequisite flags overridden by segment or identity overrides will satisfy dependent flags.
Flag dependencies are configured per-environment.


![`coffee_machine` serving is off since `hamster_power_grid` is disabled](/img/flag-dependencies/serving-off.png)

## Adding a prerequisite to a feature flag

1. Go to the _Features_ list page.
2. Make sure you select the _environment_ on the left.
3. Select any feature in the list.
4. **Visit the _Dependencies_ tab**.
5. Click _Add prerequisite_, and choose from the list the prerequisite feature.

![Adding a prerequisite feature](/img/flag-dependencies/add-prerequisite.png)

For now, a prerequisite feature cannot have another prerequisite itself — dependencies only go one level deep. However, a feature can have as many prerequisites as necessary.

@khvn26 khvn26 Oct 16, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
For now, a prerequisite feature cannot have another prerequisite itself — dependencies only go one level deep. However, a feature can have as many prerequisites as necessary.
A feature can have as many prerequisites as necessary. We do restrict:
- Nesting levels - dependencies only go one level deep.
- Cycles - circular dependencies are not allowed.


## Removing a prerequisite

Just click the 🗑️ icon next to the prerequisite feature you want to remove in the _Dependencies_ tab.

![Removing a prerequisite feature](/img/flag-dependencies/remove-prerequisite.png)

## Change requests

When _Feature change requests_ are enabled, changes to feature prerequisites will also require approval.

@coderabbitai coderabbitai Bot Oct 15, 2026 •
edited
Loading

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

🔎 Supported by static analysis

🏁 Script executed:

#!/bin/bash
set -euo pipefail
rg -n -i -C 6 'create_flag_dependency|delete_flag_dependency|change.request' api

Repository: Flagsmith/flagsmith

Length of output: 45673

🏁 Script executed:

set -euo pipefail
printf '%s\n' '--- dependency references ---'
rg -n -i -F --glob '*.py' -e 'flag_dependency' -e 'feature_dependency' -e 'prerequisite' api | head -n 300
printf '%s\n' '--- dependency-related files ---'
rg --files api | rg -i 'depend|prereq'
printf '%s\n' '--- docs context ---'
nl -ba docs/docs/managing-flags/flag-dependencies.md | sed -n '1,90p'
printf '%s\n' '--- workflow guard definitions and uses ---'
rg -n -F --glob '*.py' -e 'ChangeRequestsEnabledError' -e 'minimum_change_request_approvals' -e 'change_requests_enabled' api | head -n 300
printf '%s\n' '--- changed documentation diff ---'
git diff 1dc9b86960d64a7aaea2de752ccc4e9f64b374ed..7796a6d3581191ee1ac3e7aac70b0645667cedc0 -- docs/docs/managing-flags/flag-dependencies.md

Repository: Flagsmith/flagsmith

Length of output: 41384

🏁 Script executed:

set -euo pipefail
printf '%s\n' '--- dependency views ---'
nl -ba api/features/dependencies/views.py
printf '%s\n' '--- dependency services ---'
nl -ba api/features/dependencies/services.py
printf '%s\n' '--- dependency permissions ---'
nl -ba api/features/dependencies/permissions.py
printf '%s\n' '--- dependency route context ---'
nl -ba api/environments/urls.py | sed -n '145,190p'
printf '%s\n' '--- feature future view guard ---'
nl -ba api/features/future/views.py | sed -n '1,120p'
printf '%s\n' '--- segment workflow handling ---'
nl -ba api/segments/views.py | sed -n '230,315p'
printf '%s\n' '--- dependency-related workflow references ---'
rg -n -i -C 8 --glob '*.py' -e 'dependencies' -e 'dependency' -e 'prerequisite' api/features/workflows api/features/versioning api/segments api/features/future | head -n 500

Repository: Flagsmith/flagsmith

Length of output: 42578

🏁 Script executed:

set -euo pipefail
nl -ba api/features/dependencies/views.py
nl -ba api/features/dependencies/services.py
rg -n -C 12 -i --glob '*.py' 'change.?request|minimum_change_request_approvals|is_change_request' api/features/dependencies api/features/future api/segments

Repository: Flagsmith/flagsmith

Length of output: 42354

🏁 Script executed:

set -euo pipefail
rg -n '^def (create_flag_dependency|delete_flag_dependency)' api/features/dependencies/services.py
sed -n '330,520p' api/features/dependencies/services.py
sed -n '520,700p' api/features/dependencies/services.py

Repository: Flagsmith/flagsmith

Length of output: 8577

Correct the change-request statement.

The dependency API checks manage permission, then creates or deletes the prerequisite override directly. It does not use the change-request guard used by the feature endpoints. These changes can therefore take effect without approval when feature change requests are enabled.

Remove the statement:

Suggested fix 
--- "a/docs/docs/managing-flags/flag-dependencies.md"
+++ "b/docs/docs/managing-flags/flag-dependencies.md"
@@ -40,6 +40,5 @@
 
 ## Change requests
 
-When _Feature change requests_ are enabled, changes to feature prerequisites will also require approval.
 
 ![Flag dependency changes wrapped in a change request](/img/flag-dependencies/requires-change-request.png)
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
When _Feature change requests_ are enabled, changes to feature prerequisites will also require approval.

@khvn26 khvn26 Oct 16, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Coming up in #8449


![Flag dependency changes wrapped in a change request](/img/flag-dependencies/requires-change-request.png)
Binary file added docs/static/img/flag-dependencies/add-prerequisite.png
View file
Open in desktop

@khvn26 khvn26 Oct 16, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For some reason, all the screenshots look pale.

Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/static/img/flag-dependencies/overview.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/static/img/flag-dependencies/remove-prerequisite.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/static/img/flag-dependencies/requires-change-request.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/static/img/flag-dependencies/serving-off.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading