Flagsmith / Flagsmith/flagsmith

docs: Clarify which flag operations require change requests vs which bypass

Open
#7,506 1 comment 0 reactions 0 assignees View on GitHub
docs
Dominant language
Python
Stars
6.6k
Forks
567
Avg merge
1d 13h
Merged PRs (30d)
121

Description

## Current state

The [change requests docs page](https://docs.flagsmith.com/advanced-use/change-requests) generically says *"attempting to change a flag value will prompt you to create a new Change Request"*. The page does not distinguish between feature-state types and which trigger the CR workflow.

## What the code does (verified in `api/features/models.py`)

FeatureState has three types determined by `identity_id` and `feature_segment_id`:

```python
@property
def type(self) -> str:
if self.identity_id and self.feature_segment_id is None:
return IDENTITY
elif self.feature_segment_id and self.identity_id is None:
return FEATURE_SEGMENT
elif self.identity_id is None and self.feature_segment_id is None:
return ENVIRONMENT
```

The `is_live` property:

```python
@property
def is_live(self) -> bool:
if self.environment.use_v2_feature_versioning:
if self.identity_id is not None:
return True
return (
self.environment_feature_version_id is not None
and self.environment_feature_version.is_live
)
```

Identity-level feature states are live immediately. CRs are tied to versioning (`environment_feature_version`). Identity-level FS does not use versioning, so it is not gated by the CR workflow.

## Implication for customers

- **Environment defaults**: require CR when enabled
- **Segment overrides**: require CR when enabled
- **Identity-level overrides**: bypass CR; live immediately

Customers ask "why didn't this require approval?" when they don't see this distinction. The docs should make the scope explicit so the behavior is predictable.

## Suggested docs addition

A small section under change requests describing which feature-state types the workflow applies to, and noting that identity-level overrides are live immediately and intentionally bypass the workflow (consistent with the use case of developer/QA targeting).

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.