Repository navigation
docs(flags): read an empty variant as disabled in get-feature-flag-result #193
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.
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
Merged
Merged
Changes from all commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
cf13d4e
docs(flags): read an empty variant as disabled in get-feature-flag-re…
turnipdabeets 578a074
docs(flags): drop an empty variant from flags-loaded listeners and $a…
turnipdabeets 4b5703f
docs(flags): read an empty variant as disabled in getAllFeatureFlags …
turnipdabeets File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
2 changes: 2 additions & 0 deletions
2
openspec/changes/archive/2026-11-06-empty-variant-disabled/.openspec.yaml
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,2 @@ | ||
| schema: spec-driven | ||
| created: 2026-11-06 |
39 changes: 39 additions & 0 deletions
39
openspec/changes/archive/2026-11-06-empty-variant-disabled/proposal.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,39 @@ | ||
| ## Why | ||
|
|
||
| A flag whose variant is the empty string `""` reads as disabled from `isFeatureEnabled` in posthog-js (browser) and posthog-android, and in posthog-ios since [posthog-ios#1001](https://github.com/PostHog/posthog-ios/pull/1001). The same SDKs still report it as `enabled: true` from `getFeatureFlagResult`, and some include it in the flags-loaded callback, so one flag reads as both enabled and disabled depending on the call ([review thread](https://github.com/PostHog/posthog-ios/pull/1001#discussion_r4449050127)). posthog-js (browser) is consistent: `""` is disabled everywhere. | ||
|
|
||
| PostHog has rejected new `""` variant keys since [PostHog/posthog#118803](https://github.com/PostHog/posthog/pull/118803) (2026-10-16), so only flags created earlier through the API, MCP or Terraform can hit this. | ||
|
|
||
| The client-side flow of `is-feature-enabled` already says only a non-empty variant string is `true`. The server-side flow, `get-feature-flag-result`, `on-feature-flags` and the `$active_feature_flags` event property don't say what an empty variant is. | ||
|
|
||
| ## What Changes | ||
|
|
||
| - **`is-feature-enabled`.** The server-side flow treats only a non-empty variant string as `true`, matching the client-side flow. | ||
| - **`get-feature-flag-result`.** A new requirement: a flag whose variant is `""` returns `enabled: false` with `variant: ""`, and `is-feature-enabled` returns `false` for it. Both flow descriptions say so. | ||
| - **`on-feature-flags`.** A new requirement: payload-carrying listeners leave a `""` flag out of the keys and variants they receive. | ||
| - **`get-feature-flags`.** A new requirement: where `getAllFeatureFlags()` returns flag result objects, a `""` flag stays in the list with `enabled: false`, matching `get-feature-flag-result`. | ||
| - **`capture`.** A new requirement: client SDKs leave a `""` flag out of `$active_feature_flags`; `$feature/<key>` still carries `""`. | ||
| - **Stale surface notes.** `reload-feature-flags` lists the Android 4.0 and Flutter 6.0 signatures, and `feature-flag-called-tracker` says Flutter 6.0 adds `sendFeatureFlagEvent` to `getFeatureFlag` and `isFeatureEnabled`. No requirement changes. | ||
| - **Acceptance.** Matching scenarios in `acceptance/public/get-feature-flag-result.feature`, `on-feature-flags.feature`, `get-feature-flags.feature` and `capture.feature`. | ||
|
|
||
| ## Capabilities | ||
|
|
||
| ### New Capabilities | ||
|
|
||
| _None._ | ||
|
|
||
| ### Modified Capabilities | ||
|
|
||
| - `get-feature-flag-result`: new **Empty variant reads as disabled** requirement, and the client and server flow descriptions. | ||
| - `on-feature-flags`: new **Empty variant is left out of the flags a listener receives** requirement. | ||
| - `get-feature-flags`: new **Flag result list reads an empty variant as disabled** requirement. | ||
| - `capture`: new **Empty variant is not an active feature flag** requirement. | ||
| - `is-feature-enabled`: the server-side flow description only (recorded in the `get-feature-flag-result` delta, since it has no requirement changes). | ||
|
|
||
| ## Impact | ||
|
|
||
| - posthog-ios 4.0, posthog-android 4.0 and posthog-flutter 6.0 change `getFeatureFlagResult().enabled` and the `enabled` of each `getAllFeatureFlags()` entry (and Flutter desktop also `isFeatureEnabled`) to `false` for an empty variant in their major releases. posthog-ios 4.0 and posthog-android 4.0 also leave it out of `PostHogFeatureFlagsLoaded` (the `onFeatureFlags` and `reloadFeatureFlags` callback payload) and `$active_feature_flags`. | ||
| - posthog-kmp treats an empty variant as disabled in `isFeatureEnabled()`, `FeatureFlagResult.enabled`, `getAllFeatureFlags()` and `$active_feature_flags` on every platform, in the release that adopts posthog-ios 4.0 and posthog-android 4.0. | ||
| - Known gap: posthog-js core and react-native still return `enabled: true` from `getFeatureFlagResult` (`getEnabledFromValue` reads any string as enabled), still pass `""` to `onFeatureFlags` listeners, and still list it in `$active_feature_flags`, while their `isFeatureEnabled` returns `false`. A follow-up should align them. | ||
| - `getFeatureFlag` and the `$feature_flag_called` response keep reporting `""`. | ||
| - Server SDKs were not audited for this case. | ||
23 changes: 23 additions & 0 deletions
23
openspec/changes/archive/2026-11-06-empty-variant-disabled/specs/capture/spec.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,23 @@ | ||
| ## ADDED Requirements | ||
|
|
||
| ### Requirement: Empty variant is not an active feature flag | ||
|
|
||
| When a client SDK stamps cached feature flags onto a captured event, a flag whose value is the empty string `""` SHALL NOT be listed in `$active_feature_flags`. Its `$feature/<key>` property SHALL still carry `""`. | ||
|
|
||
| Known gap: posthog-js core and react-native list every cached flag key in `$active_feature_flags`, including one whose value is `""`. A follow-up should leave it out there. | ||
|
|
||
| #### Scenario: Empty variant flag is left out of active feature flags (@client) | ||
| - **GIVEN** a fresh SDK acceptance test harness | ||
| - **AND** the SDK clock is fixed at "2025-01-01T00:00:00Z" | ||
| - **AND** persistent storage is empty | ||
| - **AND** the mock PostHog server is reset | ||
| - **GIVEN** the SDK is initialized with token "test-token" | ||
| - **AND** cached feature flags are: | ||
| | key | value | | ||
| | beta-ui | true | | ||
| | legacy-ui | "" | | ||
| - **WHEN** capture is called with event "Signed Up" | ||
| - **THEN** one event named "Signed Up" should be enqueued | ||
| - **AND** the enqueued event property "$active_feature_flags" should contain "beta-ui" | ||
| - **AND** the enqueued event property "$active_feature_flags" should not contain "legacy-ui" | ||
| - **AND** the enqueued event property "$feature/legacy-ui" should equal "" |
31 changes: 31 additions & 0 deletions
31
...archive/2026-11-06-empty-variant-disabled/specs/get-feature-flag-result/spec.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,31 @@ | ||
| ## ADDED Requirements | ||
|
|
||
| ### Requirement: Empty variant reads as disabled | ||
|
|
||
| A flag whose value is the empty string `""` SHALL read as disabled. The SDK SHALL return a result with `enabled: false` and `variant: ""`, and `is-feature-enabled` SHALL return `false` for it, whether or not the caller supplies a default. | ||
|
|
||
| Known gap: posthog-js core and react-native still return `enabled: true` from `getFeatureFlagResult` for `""`, because `getEnabledFromValue` reads any string as enabled, while their `isFeatureEnabled` returns `false`. A follow-up should make `getFeatureFlagResult` match. | ||
|
|
||
| #### Scenario: Empty variant flag result is disabled (@both) | ||
| - **GIVEN** a fresh SDK acceptance test harness | ||
| - **AND** the SDK clock is fixed at "2025-01-01T00:00:00Z" | ||
| - **AND** persistent storage is empty | ||
| - **AND** the mock PostHog server is reset | ||
| - **GIVEN** the SDK is initialized with token "test-token" | ||
| - **AND** cached feature flags are: | ||
| | key | value | | ||
| | legacy-ui | "" | | ||
| - **WHEN** get feature flag result "legacy-ui" is called | ||
| - **THEN** the returned feature flag result should include: | ||
| | field | value | | ||
| | key | legacy-ui | | ||
| | enabled | false | | ||
| - **AND** its variant should equal the JSON value "" | ||
| - **WHEN** is feature enabled "legacy-ui" is called | ||
| - **THEN** the returned enabled state should be false | ||
|
|
||
| ## Narrative alignment | ||
|
|
||
| When syncing this delta, in both the client-side and server-side flows, replace "Multivariate flag → `enabled = true`, `variant = '<variant>'`" with "Multivariate flag with a non-empty variant → `enabled = true`, `variant = '<variant>'`" and add "Empty variant `''` → `enabled = false`, `variant = ''`". | ||
|
|
||
| Also sync `is-feature-enabled`: in its server-side flow replace "variant string → `true`" with "non-empty variant string → `true`", matching its client-side flow. No `is-feature-enabled` requirement changes. |
22 changes: 22 additions & 0 deletions
22
...anges/archive/2026-11-06-empty-variant-disabled/specs/get-feature-flags/spec.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,22 @@ | ||
| ## ADDED Requirements | ||
|
|
||
| ### Requirement: Flag result list reads an empty variant as disabled | ||
|
|
||
| On SDKs where `getAllFeatureFlags()` returns a list of flag result objects (iOS 4.0+, Android 4.0+, Flutter 6.0+, KMP), each entry SHALL match what `get-feature-flag-result` returns for that key. A flag whose value is the empty string `""` SHALL stay in the list with `enabled: false` and `variant: ""`. SDKs that return a key → value map keep reporting `""`, as `get-feature-flag` does. | ||
|
|
||
| #### Scenario: Flag result list reads an empty variant as disabled | ||
| - **GIVEN** a fresh SDK acceptance test harness | ||
| - **AND** the SDK clock is fixed at "2025-01-01T00:00:00Z" | ||
| - **AND** persistent storage is empty | ||
| - **AND** the mock PostHog server is reset | ||
| - **GIVEN** the SDK is initialized with token "test-token" | ||
| - **AND** cached feature flags are: | ||
| | key | value | | ||
| | beta-ui | true | | ||
| | legacy-ui | "" | | ||
| - **WHEN** get all feature flag results is called | ||
| - **THEN** the returned feature flag results should include: | ||
| | key | enabled | | ||
| | beta-ui | true | | ||
| | legacy-ui | false | | ||
| - **AND** the returned feature flag result for "legacy-ui" should have variant equal to the JSON value "" |
24 changes: 24 additions & 0 deletions
24
...hanges/archive/2026-11-06-empty-variant-disabled/specs/on-feature-flags/spec.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,24 @@ | ||
| ## ADDED Requirements | ||
|
|
||
| ### Requirement: Empty variant is left out of the flags a listener receives | ||
|
|
||
| A payload-carrying listener SHALL treat a flag whose value is the empty string `""` as disabled and leave it out of the flag keys and variants it receives, like a flag whose value is `false`. Readiness-only listeners are not affected. | ||
|
|
||
| Known gap: posthog-js core and react-native pass the raw flag map, which still contains the `""` entry. A follow-up should drop it there. | ||
|
|
||
| #### Scenario: Listener does not receive an empty variant flag | ||
| - **GIVEN** a fresh SDK acceptance test harness | ||
| - **AND** the SDK clock is fixed at "2025-01-01T00:00:00Z" | ||
| - **AND** persistent storage is empty | ||
| - **AND** the mock PostHog server is reset | ||
| - **GIVEN** the SDK is initialized with token "test-token" | ||
| - **AND** a feature flag listener is registered | ||
| - **WHEN** feature flags are loaded with values: | ||
| | key | value | | ||
| | beta-ui | true | | ||
| | legacy-ui | "" | | ||
| - **THEN** the feature flag listener should be invoked | ||
| - **AND** payload-carrying feature flag listeners should receive flags: | ||
| | key | value | | ||
| | beta-ui | true | | ||
| - **AND** payload-carrying feature flag listeners should not receive flag "legacy-ui" |
13 changes: 13 additions & 0 deletions
13
openspec/changes/archive/2026-11-06-empty-variant-disabled/tasks.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,13 @@ | ||
| ## 1. Spec delta | ||
|
|
||
| - [x] 1.1 Add the **Empty variant reads as disabled** requirement to `get-feature-flag-result`, and describe empty variants in its client and server flows | ||
| - [x] 1.2 Say "non-empty variant string" in the `is-feature-enabled` server-side flow | ||
| - [x] 1.3 Add the scenario to `acceptance/public/get-feature-flag-result.feature` | ||
| - [x] 1.4 Add the **Empty variant is left out of the flags a listener receives** requirement to `on-feature-flags` and its scenario to `acceptance/public/on-feature-flags.feature` | ||
| - [x] 1.5 Add the **Empty variant is not an active feature flag** requirement to `capture` and its scenario to `acceptance/public/capture.feature` | ||
| - [x] 1.6 Add the **Flag result list reads an empty variant as disabled** requirement to `get-feature-flags` and its scenario to `acceptance/public/get-feature-flags.feature` | ||
|
|
||
| ## 2. Validation | ||
|
|
||
| - [x] 2.1 Run `openspec validate --strict` | ||
| - [x] 2.2 Sync the delta into `specs/` and archive the change |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.