Flagsmith / Flagsmith/flagsmith
docs: Clarify which flag operations require change requests vs which bypass
- 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
Assessment
This issue has not been assessed yet.