Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

feat(flags): classify whether a flag edit raises, lowers, or keeps exposure (#124163)

Gustavo H. Strassburger6c70e699621d
diff --git a/products/feature_flags/backend/exposure_change.py b/products/feature_flags/backend/exposure_change.py
new file mode 100644
index 000000000000..e0438655a2de
--- /dev/null
+++ b/products/feature_flags/backend/exposure_change.py
@@ -0,0 +1,358 @@
+"""Whether an edit of a feature flag raises, lowers, or keeps the share of people who get a value of the flag.
+
+Flag rollback suggestions watch the errors after an edit that raises exposure, and the flag page asks why after an
+edit that lowers it. Both read the edit here, so they agree on its direction. An edit is a change to the flag's
+`filters`, `active`, `deleted`, key, bucketing identifier or experience continuity. The flag's `version` also changes
+when a cohort or a flag that the flag uses changes, so it is not an input.
+
+The flag service gives each person the value of the first condition that matches them. Which people match two
+conditions depends on the data, not on the config, so the config alone cannot tell who gets another value. The
+classification is therefore conservative. An edit lowers exposure only when it takes values away and gives nobody
+another value. Any other edit that can change who gets which value raises it. A raise that reaches nobody costs
+little, because the rollback suggestion then finds nobody with a new value and stops watching the errors. A missed
+raise lets a bad rollout through.
+
+Not covered: the holdout, because only experiments write it, and their flags are out of scope. Early access enrollment
+and the other super groups, because the early access product owns those flags. Turning `early_exit` on, which takes
+values away from the people outside a condition's rollout. It changes how the conditions combine and rolls nothing
+back, so the flag page does not ask why. The flag-level aggregation is covered, because it decides whether the flag
+counts persons or groups.
+"""
+
+from collections.abc import Mapping
+from enum import StrEnum
+from typing import Any
+
+from posthog.dataclasses import frozen
+
+from products.feature_flags.backend.facade.config import require_v1_config
+from products.feature_flags.backend.facade.edits import (
+ ReleaseCondition,
+ ReleaseConditions,
+ Split,
+ group_type_index,
+ moves_people,
+ normalized_bucketing_identifier,
+ normalized_experience_continuity,
+ pair_conditions,
+ parse_release_conditions,
+ parse_variants,
+ same_assignment,
+ served_slots,
+ split_variant_keys,
+)
+
+
+class ExposureChangeKind(StrEnum):
+ # The flag was enabled or restored.
+ ENABLED = "enabled"
+ # The flag was disabled or deleted.
+ DISABLED = "disabled"
+ ROLLOUT_INCREASED = "rollout_increased"
+ ROLLOUT_DECREASED = "rollout_decreased"
+ CONDITION_ADDED = "condition_added"
+ CONDITION_REMOVED = "condition_removed"
+ # The criteria of a condition changed, or the flag-level aggregation changed.
+ CRITERIA_CHANGED = "criteria_changed"
+ VARIANT_CHANGED = "variant_changed"
+ # The conditions have a new order, and the order decides the value of a person who matches two of them.
+ CONDITIONS_REORDERED = "conditions_reordered"
+ # A person whose properties match a condition and whose hash is outside its rollout now gets the value of a later
+ # condition, not false.
+ EARLY_EXIT_TURNED_OFF = "early_exit_turned_off"
+ # The flag key, the bucketing identifier or experience continuity changed, so the hash gives people a new draw.
+ BUCKETING_CHANGED = "bucketing_changed"
+
+
+_LOWERING_KINDS = frozenset(
+ {ExposureChangeKind.DISABLED, ExposureChangeKind.ROLLOUT_DECREASED, ExposureChangeKind.CONDITION_REMOVED}
+)
+
+
+class ExposureDirection(StrEnum):
+ RAISES = "raises"
+ LOWERS = "lowers"
+ KEEPS = "keeps"
+
+
+@frozen
+class FlagExposureConfig:
+ """The fields of a flag on one side of an edit that decide who gets which value."""
+
+ active: bool
+ filters: Mapping[str, Any] | None
+ key: str
+ bucketing_identifier: str | None
+ ensure_experience_continuity: bool | None
+ deleted: bool = False
+
+
+@frozen
+class ExposureChange:
+ kinds: frozenset[ExposureChangeKind]
+ direction: ExposureDirection
+ # The variants that the flag can serve after the edit, from the split and from the variant overrides. After a
+ # raise, the rollback suggestion counts the people with any value other than false, and the people with each
+ # variant. Empty for a boolean flag, and for a disabled or deleted flag.
+ served_variants: tuple[str, ...]
+
+
+@frozen
+class _Side:
+ split: Split
+ conditions: ReleaseConditions
+ aggregation: int | None
+ early_exit: bool
+ buckets_on_device_id: bool
+
+
+class _ChangeBuilder:
+ def __init__(self) -> None:
+ self._kinds: set[ExposureChangeKind] = set()
+ self._raises = False
+
+ def add(self, kind: ExposureChangeKind, *, gives_another_value: bool = False) -> None:
+ self._kinds.add(kind)
+ self._raises = self._raises or kind not in _LOWERING_KINDS or gives_another_value
+
+ def direction(self) -> ExposureDirection:
+ if self._raises:
+ return ExposureDirection.RAISES
+ if self._kinds:
+ return ExposureDirection.LOWERS
+ return ExposureDirection.KEEPS
+
+ def kinds(self) -> frozenset[ExposureChangeKind]:
+ return frozenset(self._kinds)
+
+
+def _serves_anybody(side: _Side) -> bool:
+ return any(condition.rollout > 0 for condition in side.conditions)
+
+
+def _serves_from_split(side: _Side) -> bool:
+ return any(condition.rollout > 0 and condition.variant is None for condition in side.conditions)
+
+
+def _served_variants(side: _Side) -> tuple[str, ...]:
+ variants: dict[str, None] = {}
+ if _serves_from_split(side):
+ variants.update(dict.fromkeys(variant.key for variant in served_slots(side.split) if variant.key))
+ variants.update(
+ dict.fromkeys(condition.variant for condition in side.conditions if condition.rollout > 0 and condition.variant)
+ )
+ return tuple(variants)
+
+
+def _ends_evaluation(condition: ReleaseCondition, side: _Side) -> bool:
+ # A condition ends the evaluation for the people whose properties match it and whose hash is inside its rollout.
+ # With early exit, it also ends the evaluation for the people outside its rollout: they get false, and the flag
+ # service reads no later condition for them.
+ # See `get_match` in rust/feature-flags/src/flags/flag_matching.rs.
+ # A condition at 0% then still decides who gets false.
+ return condition.rollout > 0 or side.early_exit
+
+
+def _gives_false_outside_rollout(condition: ReleaseCondition, side: _Side) -> bool:
+ # The value of a later condition then does not reach the people that this condition matches outside its rollout.
+ return side.early_exit and condition.rollout < 100
+
+
+# The variant override of a condition, or None with the group type whose key the split hashes.
+_Value = tuple[str | None, int | None]
+
+
+def _value(condition: ReleaseCondition, side: _Side) -> _Value:
+ # The split hashes the group key for a group condition and the person for a person condition, so two conditions
+ # of different group types give a person different draws of the same split. A boolean flag serves true for both.
+ if condition.variant or not served_slots(side.split):
+ return (condition.variant, None)
+ return (None, condition.aggregation)
+
+
+def _gives_another_value(old_condition: ReleaseCondition, new: _Side, served_after: set[_Value]) -> bool:
+ # A person that `old_condition` no longer serves gets the value of a later condition that matches them, which can
+ # differ from the value `old_condition` gave them. Positions are not compared, so a served condition anywhere in
+ # the flag counts, which errs toward a raise.
+ old_value = _value(old_condition, new)
+ return any(value != old_value for value in served_after)
+
+
+def _needs_bucketing_hash(condition: ReleaseCondition, side: _Side) -> bool:
+ # The same rule as `condition_needs_bucketing_hash` in rust/feature-flags/src/flags/flag_operations.rs. The hash
+ # decides the result of a condition below 100%. It also decides the result of a condition that serves from a
+ # split whose first served variant is below 100%, because a hash past that variant gets another variant, or true
+ # when the split covers less than 100%. Under device ID bucketing, the flag service skips a person condition that
+ # needs the hash for a request without a device ID, a condition at 0% included.
+ if condition.rollout < 100:
+ return True
+ slots = served_slots(side.split)
+ if not slots or condition.variant is not None:
+ return False
+ first = slots[0].rollout_percentage
+ return first is None or first < 100
+
+
+def _skipped_without_device_id(condition: ReleaseCondition, side: _Side) -> bool:
+ return side.buckets_on_device_id and condition.aggregation is None and _needs_bucketing_hash(condition, side)
+
+
+def _reads_bucketing(side: _Side, *, persons_only: bool = False) -> bool:
+ # A condition that ends the evaluation for nobody gives the same result whatever the hash is. A condition at 0%
+ # with early exit counts, which errs toward a raise for a new key: the hash does not change its result, but a
+ # change to device ID bucketing makes the flag service skip it.
+ return any(
+ _ends_evaluation(condition, side) and _needs_bucketing_hash(condition, side)
+ for condition in side.conditions
+ if not persons_only or condition.aggregation is None
+ )
+
+
+def _person_hash_inputs(config: FlagExposureConfig, side: _Side) -> tuple[str, bool]:
+ identifier = normalized_bucketing_identifier(config.bucketing_identifier)
+ # The flag service reads experience continuity only for a person flag that buckets on the distinct ID. See
+ # `has_experience_continuity` in rust/feature-flags/src/flags/flag_operations.rs.
+ continuity = (
+ identifier == "distinct_id"
+ and side.aggregation is None
+ and normalized_experience_continuity(config.ensure_experience_continuity)
+ )
+ return identifier, continuity
+
+
+def _changes_bucketing(before: FlagExposureConfig, after: FlagExposureConfig, old: _Side, new: _Side) -> bool:
+ # The flag service hashes the flag key with the group key for a group condition. For a person condition, it uses
+ # the device ID or the distinct ID, as the bucketing identifier says. With experience continuity, it uses an
+ # override row or the anonymous ID that the request sends. See `hashed_identifier` in
+ # rust/feature-flags/src/flags/flag_matching.rs. Turning continuity on also moves people, because the request's
+ # anonymous ID and the override rows from an earlier period of continuity then replace the distinct ID.
+ # A deleted flag does not get here, so the tombstone suffix of a deleted flag's key is not a new key.
+ if before.key != after.key and _reads_bucketing(new):
+ return True
+ return _person_hash_inputs(before, old) != _person_hash_inputs(after, new) and _reads_bucketing(
+ new, persons_only=True
+ )
+
+
+def _reordered(pairs: Mapping[int, int]) -> bool:
+ order = [pairs[new_index] for new_index in sorted(pairs)]
+ return any(earlier > later for earlier, later in zip(order, order[1:]))
+
+
+def _side(config: FlagExposureConfig) -> _Side:
+ filters = config.filters or {}
+ multivariate = filters.get("multivariate")
+ split = parse_variants(multivariate.get("variants") if isinstance(multivariate, Mapping) else None)
+ aggregation = group_type_index(filters.get("aggregation_group_type_index"))
+ return _Side(
+ split=split,
+ conditions=parse_release_conditions(
+ filters.get("groups"), flag_aggregation=aggregation, variant_keys=split_variant_keys(split)
+ ),
+ aggregation=aggregation,
+ early_exit=filters.get("early_exit") is True,
+ buckets_on_device_id=normalized_bucketing_identifier(config.bucketing_identifier) == "device_id",
+ )
+
+
+def _compare_pair(
+ previous: ReleaseCondition,
+ condition: ReleaseCondition,
+ *,
+ old: _Side,
+ new: _Side,
+ served_after: set[_Value],
+ builder: _ChangeBuilder,
+) -> None:
+ if not _ends_evaluation(previous, old) and not _ends_evaluation(condition, new):
+ return
+ if previous.criteria != condition.criteria and _ends_evaluation(condition, new):
+ builder.add(ExposureChangeKind.CRITERIA_CHANGED)
+ if condition.rollout > previous.rollout:
+ builder.add(ExposureChangeKind.ROLLOUT_INCREASED)
+ elif condition.rollout < previous.rollout:
+ # With early exit, the people outside the new rollout get false, not the value of a later condition. A request
+ # that skips the condition for a missing device ID can still get that value.
+ builder.add(
+ ExposureChangeKind.ROLLOUT_DECREASED,
+ gives_another_value=(not new.early_exit or _skipped_without_device_id(condition, new))
+ and _gives_another_value(previous, new, served_after),
+ )
+ if condition.rollout > 0 and moves_people(previous, condition):
+ builder.add(ExposureChangeKind.VARIANT_CHANGED)
+
+
+def _compare_conditions(old: _Side, new: _Side, builder: _ChangeBuilder) -> None:
+ pairs = pair_conditions(old.conditions, new.conditions)
+ served_after = {_value(condition, new) for condition in new.conditions if condition.rollout > 0}
+ for new_index, condition in enumerate(new.conditions):
+ if new_index in pairs:
+ previous = old.conditions[pairs[new_index]]
+ _compare_pair(previous, condition, old=old, new=new, served_after=served_after, builder=builder)
+ elif _ends_evaluation(condition, new):
+ builder.add(ExposureChangeKind.CONDITION_ADDED)
+
+ paired_before = set(pairs.values())
+ for old_index, removed in enumerate(old.conditions):
+ if old_index in paired_before or not _ends_evaluation(removed, old):
+ continue
+ # With early exit, the people that the removed condition gave false can get the value of a later condition.
+ builder.add(
+ ExposureChangeKind.CONDITION_REMOVED,
+ gives_another_value=_gives_false_outside_rollout(removed, old)
+ or _gives_another_value(removed, new, served_after),
+ )
+
+ # A new order gives a person who matches two conditions the value of the one that comes first now. Which pairs
+ # of conditions overlap is not known here, so any reorder of conditions with different values counts, and so does
+ # a reorder of a condition that gives false outside its rollout. A condition that ends the evaluation for nobody
+ # on either side cannot move anybody.
+ deciding = {
+ new_index: old_index
+ for new_index, old_index in pairs.items()
+ if _ends_evaluation(new.conditions[new_index], new) and _ends_evaluation(old.conditions[old_index], old)
+ }
+ kept_values = {
+ _value(new.conditions[new_index], new) for new_index in deciding if new.conditions[new_index].rollout > 0
+ }
+ gives_false = any(_gives_false_outside_rollout(new.conditions[new_index], new) for new_index in deciding)
+ if _reordered(deciding) and (gives_false or len(kept_values) > 1):
+ builder.add(ExposureChangeKind.CONDITIONS_REORDERED)
+
+
+def classify_exposure_change(*, before: FlagExposureConfig, after: FlagExposureConfig) -> ExposureChange:
+ """Raises `ConfigFormatError` for a config that is not version 1."""
+ require_v1_config(before.filters)
+ require_v1_config(after.filters)
+ old = _side(before)
+ new = _side(after)
+ # A disabled or deleted flag serves nobody, so an edit of one changes nothing until the flag is enabled or
+ # restored. See the `deleted = false` filter in rust/feature-flags/src/flags/feature_flag_list.rs.
+ was_on = before.active and not before.deleted
+ is_on = after.active and not after.deleted
+ builder = _ChangeBuilder()
+
+ if was_on and is_on:
+ if old.aggregation != new.aggregation and _serves_anybody(new):
+ builder.add(ExposureChangeKind.CRITERIA_CHANGED)
+ if (
+ not new.early_exit
+ and any(_gives_false_outside_rollout(condition, old) for condition in old.conditions)
+ and _serves_anybody(new)
+ ):
+ builder.add(ExposureChangeKind.EARLY_EXIT_TURNED_OFF)
+ if _changes_bucketing(before, after, old, new):
+ builder.add(ExposureChangeKind.BUCKETING_CHANGED)
+ _compare_conditions(old, new, builder)
+ if not same_assignment(old.split, new.split) and _serves_from_split(new):
+ builder.add(ExposureChangeKind.VARIANT_CHANGED)
+ elif is_on and _serves_anybody(new):
+ builder.add(ExposureChangeKind.ENABLED)
+ elif was_on and _serves_anybody(old):
+ builder.add(ExposureChangeKind.DISABLED)
+
+ return ExposureChange(
+ kinds=builder.kinds(),
+ direction=builder.direction(),
+ served_variants=_served_variants(new) if is_on else (),
+ )
diff --git a/products/feature_flags/backend/facade/edits.py b/products/feature_flags/backend/facade/edits.py
index e4c803b6c75c..31a4250342e9 100644
--- a/products/feature_flags/backend/facade/edits.py
+++ b/products/feature_flags/backend/facade/edits.py
@@ -151,7 +151,7 @@ def parse_release_conditions(
) -> ReleaseConditions:
"""`variant_keys` are the variants of the flag in the same version, because the flag service ignores an
override that names no variant of the flag."""
- aggregation = _group_type_index(flag_aggregation)
+ aggregation = group_type_index(flag_aggregation)
return tuple(_condition(group, aggregation, variant_keys) for group in groups) if isinstance(groups, list) else ()
@@ -283,7 +283,7 @@ def _condition(group: object, flag_aggregation: int | None, variant_keys: Collec
sort_keys=True,
default=str,
),
- aggregation=_group_type_index(aggregation),
+ aggregation=group_type_index(aggregation),
property_keys=frozenset(_property_key(prop) for prop in properties)
if isinstance(properties, list)
else frozenset(),
@@ -362,7 +362,7 @@ def conditions_follow_flag_aggregation(aggregation: object, conditions: Sequence
`changes_that_apply` relies on this, because it reads only the flag-level aggregation of each save. The flag
serializer keeps it true: it sets the flag-level aggregation to null when the conditions mix aggregations.
"""
- flag_aggregation = _group_type_index(aggregation)
+ flag_aggregation = group_type_index(aggregation)
return flag_aggregation is None or all(
condition_aggregation(condition, flag_aggregation) is not None
for condition in conditions
@@ -443,12 +443,21 @@ def _normalized(setting: BucketingSetting, value: object, feature_flag_id: int)
tombstone = f":deleted:{feature_flag_id}"
return value.removesuffix(tombstone)
case BucketingSetting.AGGREGATION:
- return _group_type_index(value)
+ return group_type_index(value)
case BucketingSetting.BUCKETING_IDENTIFIER:
- return "device_id" if value == "device_id" else "distinct_id"
+ return normalized_bucketing_identifier(value)
case BucketingSetting.EXPERIENCE_CONTINUITY:
- return value is True
+ return normalized_experience_continuity(value)
-def _group_type_index(value: object) -> int | None:
+def group_type_index(value: object) -> int | None:
+ # A boolean is not a group type index, and Python's `True == 1` would let one through.
return value if isinstance(value, int) and not isinstance(value, bool) else None
+
+
+def normalized_bucketing_identifier(value: object) -> str:
+ return "device_id" if value == "device_id" else "distinct_id"
+
+
+def normalized_experience_continuity(value: object) -> bool:
+ return value is True
diff --git a/products/feature_flags/backend/test/test_exposure_change.py b/products/feature_flags/backend/test/test_exposure_change.py
new file mode 100644
index 000000000000..65e16e566415
--- /dev/null
+++ b/products/feature_flags/backend/test/test_exposure_change.py
@@ -0,0 +1,527 @@
+from typing import Any
+
+from unittest import TestCase
+
+from parameterized import parameterized
+
+from products.feature_flags.backend.exposure_change import (
+ ExposureChangeKind,
+ ExposureDirection,
+ FlagExposureConfig,
+ classify_exposure_change,
+)
+from products.feature_flags.backend.facade.config import ConfigFormatError
+
+EMAIL = [{"key": "email", "type": "person", "operator": "icontains", "value": "@example.com"}]
+OTHER_EMAIL = [{"key": "email", "type": "person", "operator": "icontains", "value": "@example.org"}]
+SPLIT_50_50 = [{"key": "a", "rollout_percentage": 50}, {"key": "b", "rollout_percentage": 50}]
+SPLIT_ALL_A = [{"key": "a", "rollout_percentage": 100}, {"key": "b", "rollout_percentage": 0}]
+SPLIT_40_A = [{"key": "a", "rollout_percentage": 40}, {"key": "b", "rollout_percentage": 0}]
+
+ENABLED = ExposureChangeKind.ENABLED
+DISABLED = ExposureChangeKind.DISABLED
+ROLLOUT_INCREASED = ExposureChangeKind.ROLLOUT_INCREASED
+ROLLOUT_DECREASED = ExposureChangeKind.ROLLOUT_DECREASED
+CONDITION_ADDED = ExposureChangeKind.CONDITION_ADDED
+CONDITION_REMOVED = ExposureChangeKind.CONDITION_REMOVED
+CRITERIA_CHANGED = ExposureChangeKind.CRITERIA_CHANGED
+VARIANT_CHANGED = ExposureChangeKind.VARIANT_CHANGED
+CONDITIONS_REORDERED = ExposureChangeKind.CONDITIONS_REORDERED
+EARLY_EXIT_TURNED_OFF = ExposureChangeKind.EARLY_EXIT_TURNED_OFF
+BUCKETING_CHANGED = ExposureChangeKind.BUCKETING_CHANGED
+RAISES = ExposureDirection.RAISES
+LOWERS = ExposureDirection.LOWERS
+KEEPS = ExposureDirection.KEEPS
+
+
+def _condition(
+ rollout: float,
+ properties: list[dict[str, Any]] | None = None,
+ variant: str | None = None,
+ aggregation: int | None = None,
+) -> dict[str, Any]:
+ condition: dict[str, Any] = {"properties": properties or [], "rollout_percentage": rollout, "variant": variant}
+ if aggregation is not None:
+ condition["aggregation_group_type_index"] = aggregation
+ return condition
+
+
+def _flag(
+ *conditions: dict[str, Any],
+ active: bool = True,
+ deleted: bool = False,
+ variants: list[dict[str, Any]] | None = None,
+ aggregation: int | None = None,
+ early_exit: bool = False,
+ key: str = "flag",
+ bucketing_identifier: str | None = None,
+ ensure_experience_continuity: bool | None = False,
+) -> FlagExposureConfig:
+ filters: dict[str, Any] = {
+ "groups": list(conditions),
+ "aggregation_group_type_index": aggregation,
+ "early_exit": early_exit,
+ }
+ if variants is not None:
+ filters["multivariate"] = {"variants": variants}
+ return FlagExposureConfig(
+ active=active,
+ deleted=deleted,
+ filters=filters,
+ key=key,
+ bucketing_identifier=bucketing_identifier,
+ ensure_experience_continuity=ensure_experience_continuity,
+ )
+
+
+VERSION_2 = FlagExposureConfig(
+ active=True, filters={"version": 2}, key="flag", bucketing_identifier=None, ensure_experience_continuity=False
+)
+
+
+class TestClassifyExposureChange(TestCase):
+ @parameterized.expand(
+ [
+ ("no_change", _flag(_condition(50)), _flag(_condition(50)), set(), KEEPS),
+ (
+ "edit_of_a_disabled_flag",
+ _flag(_condition(10), active=False),
+ _flag(_condition(100), active=False),
+ set(),
+ KEEPS,
+ ),
+ ("enabled", _flag(_condition(0), active=False), _flag(_condition(50)), {ENABLED}, RAISES),
+ ("enabled_at_zero_rollout", _flag(_condition(0), active=False), _flag(_condition(0)), set(), KEEPS),
+ ("disabled", _flag(_condition(50)), _flag(_condition(0), active=False), {DISABLED}, LOWERS),
+ ("disabled_at_zero_rollout", _flag(_condition(0)), _flag(_condition(0), active=False), set(), KEEPS),
+ ("restored", _flag(_condition(50), deleted=True), _flag(_condition(50)), {ENABLED}, RAISES),
+ ("deleted", _flag(_condition(50)), _flag(_condition(50), deleted=True), {DISABLED}, LOWERS),
+ ("rollout_increased", _flag(_condition(0)), _flag(_condition(50)), {ROLLOUT_INCREASED}, RAISES),
+ ("rollout_decreased", _flag(_condition(50)), _flag(_condition(10)), {ROLLOUT_DECREASED}, LOWERS),
+ (
+ "condition_added",
+ _flag(_condition(100, EMAIL)),
+ _flag(_condition(100, EMAIL), _condition(20)),
+ {CONDITION_ADDED},
+ RAISES,
+ ),
+ (
+ "condition_added_at_zero_rollout",
+ _flag(_condition(100, EMAIL)),
+ _flag(_condition(100, EMAIL), _condition(0)),
+ set(),
+ KEEPS,
+ ),
+ (
+ "condition_removed_at_zero_rollout",
+ _flag(_condition(0, EMAIL), _condition(100)),
+ _flag(_condition(100)),
+ set(),
+ KEEPS,
+ ),
+ (
+ "condition_at_zero_rollout_moved",
+ _flag(
+ _condition(0, OTHER_EMAIL),
+ _condition(100, EMAIL, variant="a"),
+ _condition(100, variant="b"),
+ variants=SPLIT_50_50,
+ ),
+ _flag(
+ _condition(100, EMAIL, variant="a"),
+ _condition(100, variant="b"),
+ _condition(0, OTHER_EMAIL),
+ variants=SPLIT_50_50,
+ ),
+ set(),
+ KEEPS,
+ ),
+ (
+ "condition_removed",
+ _flag(_condition(100, EMAIL), _condition(20)),
+ _flag(_condition(100, EMAIL)),
+ {CONDITION_REMOVED},
+ LOWERS,
+ ),
+ (
+ "properties_changed",
+ _flag(_condition(100, EMAIL)),
+ _flag(_condition(100, OTHER_EMAIL)),
+ {CRITERIA_CHANGED},
+ RAISES,
+ ),
+ (
+ "properties_changed_on_a_condition_turned_off",
+ _flag(_condition(50, EMAIL)),
+ _flag(_condition(0, OTHER_EMAIL)),
+ {ROLLOUT_DECREASED},
+ LOWERS,
+ ),
+ (
+ "flag_aggregation_changed",
+ _flag(_condition(100)),
+ _flag(_condition(100), aggregation=0),
+ {CRITERIA_CHANGED},
+ RAISES,
+ ),
+ (
+ "flag_aggregation_changed_on_a_flag_that_serves_nobody",
+ _flag(_condition(0)),
+ _flag(_condition(0), aggregation=0),
+ set(),
+ KEEPS,
+ ),
+ (
+ "split_changed",
+ _flag(_condition(100), variants=SPLIT_50_50),
+ _flag(
+ _condition(100),
+ variants=[{"key": "a", "rollout_percentage": 30}, {"key": "b", "rollout_percentage": 70}],
+ ),
+ {VARIANT_CHANGED},
+ RAISES,
+ ),
+ (
+ "split_changed_while_every_condition_has_an_override",
+ _flag(_condition(100, variant="a"), variants=SPLIT_50_50),
+ _flag(
+ _condition(100, variant="a"),
+ variants=[{"key": "a", "rollout_percentage": 30}, {"key": "b", "rollout_percentage": 70}],
+ ),
+ set(),
+ KEEPS,
+ ),
+ (
+ "multivariate_flag_made_boolean",
+ _flag(_condition(100), variants=SPLIT_50_50),
+ _flag(_condition(100)),
+ {VARIANT_CHANGED},
+ RAISES,
+ ),
+ (
+ "override_added",
+ _flag(_condition(100), variants=SPLIT_50_50),
+ _flag(_condition(100, variant="b"), variants=SPLIT_50_50),
+ {VARIANT_CHANGED},
+ RAISES,
+ ),
+ (
+ "override_changed_on_a_condition_turned_off",
+ _flag(_condition(50, variant="b"), variants=SPLIT_50_50),
+ _flag(_condition(0, variant="a"), variants=SPLIT_50_50),
+ {ROLLOUT_DECREASED},
+ LOWERS,
+ ),
+ (
+ "rollout_lowered_on_a_multivariate_flag_without_overrides",
+ _flag(_condition(50, EMAIL), _condition(100), variants=SPLIT_50_50),
+ _flag(_condition(10, EMAIL), _condition(100), variants=SPLIT_50_50),
+ {ROLLOUT_DECREASED},
+ LOWERS,
+ ),
+ (
+ "lowered_override_condition_falls_through_to_another_variant",
+ _flag(_condition(100, EMAIL, variant="b"), _condition(100), variants=SPLIT_50_50),
+ _flag(_condition(10, EMAIL, variant="b"), _condition(100), variants=SPLIT_50_50),
+ {ROLLOUT_DECREASED},
+ RAISES,
+ ),
+ (
+ "lowered_override_condition_with_early_exit",
+ _flag(_condition(100, EMAIL, variant="b"), _condition(100), variants=SPLIT_50_50, early_exit=True),
+ _flag(_condition(10, EMAIL, variant="b"), _condition(100), variants=SPLIT_50_50, early_exit=True),
+ {ROLLOUT_DECREASED},
+ LOWERS,
+ ),
+ (
+ "lowered_override_condition_with_early_exit_under_device_id_bucketing",
+ _flag(
+ _condition(100, EMAIL, variant="b"),
+ _condition(100),
+ variants=SPLIT_50_50,
+ early_exit=True,
+ bucketing_identifier="device_id",
+ ),
+ _flag(
+ _condition(10, EMAIL, variant="b"),
+ _condition(100),
+ variants=SPLIT_50_50,
+ early_exit=True,
+ bucketing_identifier="device_id",
+ ),
+ {ROLLOUT_DECREASED},
+ RAISES,
+ ),
+ (
+ "removed_override_condition_falls_through_to_another_variant",
+ _flag(_condition(100, EMAIL, variant="b"), _condition(100), variants=SPLIT_50_50),
+ _flag(_condition(100), variants=SPLIT_50_50),
+ {CONDITION_REMOVED},
+ RAISES,
+ ),
+ (
+ "condition_at_zero_rollout_removed_with_early_exit",
+ _flag(_condition(0, EMAIL), _condition(100), early_exit=True),
+ _flag(_condition(100), early_exit=True),
+ {CONDITION_REMOVED},
+ RAISES,
+ ),
+ (
+ "properties_changed_on_a_condition_at_zero_rollout_with_early_exit",
+ _flag(_condition(0, EMAIL), _condition(100), early_exit=True),
+ _flag(_condition(0, OTHER_EMAIL), _condition(100), early_exit=True),
+ {CRITERIA_CHANGED},
+ RAISES,
+ ),
+ (
+ "condition_at_zero_rollout_moved_with_early_exit",
+ _flag(_condition(0, EMAIL), _condition(100), early_exit=True),
+ _flag(_condition(100), _condition(0, EMAIL), early_exit=True),
+ {CONDITIONS_REORDERED},
+ RAISES,
+ ),
+ (
+ "early_exit_turned_off",
+ _flag(_condition(10, EMAIL), _condition(100), early_exit=True),
+ _flag(_condition(10, EMAIL), _condition(100)),
+ {EARLY_EXIT_TURNED_OFF},
+ RAISES,
+ ),
+ (
+ "early_exit_turned_off_with_a_lower_rollout",
+ _flag(_condition(50, EMAIL), _condition(100), early_exit=True),
+ _flag(_condition(10, EMAIL), _condition(100)),
+ {EARLY_EXIT_TURNED_OFF, ROLLOUT_DECREASED},
+ RAISES,
+ ),
+ (
+ "early_exit_turned_off_at_full_rollout",
+ _flag(_condition(100, EMAIL), _condition(100), early_exit=True),
+ _flag(_condition(100, EMAIL), _condition(100)),
+ set(),
+ KEEPS,
+ ),
+ (
+ "early_exit_turned_on",
+ _flag(_condition(10, EMAIL), _condition(100)),
+ _flag(_condition(10, EMAIL), _condition(100), early_exit=True),
+ set(),
+ KEEPS,
+ ),
+ (
+ "group_condition_removed_before_a_person_condition",
+ _flag(_condition(100, aggregation=0), _condition(100), variants=SPLIT_50_50),
+ _flag(_condition(100), variants=SPLIT_50_50),
+ {CONDITION_REMOVED},
+ RAISES,
+ ),
+ (
+ "group_and_person_conditions_reordered",
+ _flag(_condition(100, aggregation=0), _condition(100), variants=SPLIT_50_50),
+ _flag(_condition(100), _condition(100, aggregation=0), variants=SPLIT_50_50),
+ {CONDITIONS_REORDERED},
+ RAISES,
+ ),
+ (
+ "group_and_person_conditions_of_a_boolean_flag_reordered",
+ _flag(_condition(100, aggregation=0), _condition(100)),
+ _flag(_condition(100), _condition(100, aggregation=0)),
+ set(),
+ KEEPS,
+ ),
+ (
+ "conditions_with_different_overrides_reordered",
+ _flag(_condition(100, EMAIL, variant="a"), _condition(100, variant="b"), variants=SPLIT_50_50),
+ _flag(_condition(100, variant="b"), _condition(100, EMAIL, variant="a"), variants=SPLIT_50_50),
+ {CONDITIONS_REORDERED},
+ RAISES,
+ ),
+ (
+ "conditions_of_a_boolean_flag_reordered",
+ _flag(_condition(10, EMAIL), _condition(100)),
+ _flag(_condition(100), _condition(10, EMAIL)),
+ set(),
+ KEEPS,
+ ),
+ (
+ "conditions_reordered_with_early_exit",
+ _flag(_condition(10, EMAIL), _condition(100), early_exit=True),
+ _flag(_condition(100), _condition(10, EMAIL), early_exit=True),
+ {CONDITIONS_REORDERED},
+ RAISES,
+ ),
+ (
+ "conditions_at_full_rollout_reordered_with_early_exit",
+ _flag(_condition(100, EMAIL), _condition(100), early_exit=True),
+ _flag(_condition(100), _condition(100, EMAIL), early_exit=True),
+ set(),
+ KEEPS,
+ ),
+ ("key_changed", _flag(_condition(50)), _flag(_condition(50), key="renamed"), {BUCKETING_CHANGED}, RAISES),
+ (
+ "key_changed_at_full_rollout",
+ _flag(_condition(100)),
+ _flag(_condition(100), key="renamed"),
+ set(),
+ KEEPS,
+ ),
+ (
+ "key_changed_on_a_split",
+ _flag(_condition(100), variants=SPLIT_50_50),
+ _flag(_condition(100), variants=SPLIT_50_50, key="renamed"),
+ {BUCKETING_CHANGED},
+ RAISES,
+ ),
+ (
+ "bucketing_identifier_changed",
+ _flag(_condition(50)),
+ _flag(_condition(50), bucketing_identifier="device_id"),
+ {BUCKETING_CHANGED},
+ RAISES,
+ ),
+ (
+ "bucketing_identifier_changed_on_a_group_flag",
+ _flag(_condition(50), aggregation=0),
+ _flag(_condition(50), aggregation=0, bucketing_identifier="device_id"),
+ set(),
+ KEEPS,
+ ),
+ (
+ "key_changed_on_a_group_flag",
+ _flag(_condition(50), aggregation=0),
+ _flag(_condition(50), aggregation=0, key="renamed"),
+ {BUCKETING_CHANGED},
+ RAISES,
+ ),
+ (
+ "bucketing_identifier_written_as_the_default",
+ _flag(_condition(50)),
+ _flag(_condition(50), bucketing_identifier="distinct_id"),
+ set(),
+ KEEPS,
+ ),
+ (
+ "experience_continuity_turned_on",
+ _flag(_condition(50)),
+ _flag(_condition(50), ensure_experience_continuity=True),
+ {BUCKETING_CHANGED},
+ RAISES,
+ ),
+ (
+ "experience_continuity_turned_off",
+ _flag(_condition(50), ensure_experience_continuity=True),
+ _flag(_condition(50), ensure_experience_continuity=None),
+ {BUCKETING_CHANGED},
+ RAISES,
+ ),
+ (
+ "experience_continuity_turned_on_under_device_id_bucketing",
+ _flag(_condition(50), bucketing_identifier="device_id"),
+ _flag(_condition(50), bucketing_identifier="device_id", ensure_experience_continuity=True),
+ set(),
+ KEEPS,
+ ),
+ (
+ "experience_continuity_turned_on_for_a_person_condition_of_a_group_flag",
+ _flag({**_condition(50), "aggregation_group_type_index": None}, aggregation=0),
+ _flag(
+ {**_condition(50), "aggregation_group_type_index": None},
+ aggregation=0,
+ ensure_experience_continuity=True,
+ ),
+ set(),
+ KEEPS,
+ ),
+ (
+ "key_changed_on_a_partially_allocated_split",
+ _flag(_condition(100), variants=SPLIT_40_A),
+ _flag(_condition(100), variants=SPLIT_40_A, key="renamed"),
+ {BUCKETING_CHANGED},
+ RAISES,
+ ),
+ (
+ "key_changed_with_a_condition_at_zero_rollout",
+ _flag(_condition(0, EMAIL), _condition(100)),
+ _flag(_condition(0, EMAIL), _condition(100), key="renamed"),
+ set(),
+ KEEPS,
+ ),
+ (
+ "bucketing_identifier_changed_with_a_blocker_at_zero_rollout",
+ _flag(_condition(0, EMAIL), _condition(100), early_exit=True),
+ _flag(_condition(0, EMAIL), _condition(100), early_exit=True, bucketing_identifier="device_id"),
+ {BUCKETING_CHANGED},
+ RAISES,
+ ),
+ (
+ "rollout_increased_and_condition_removed",
+ _flag(_condition(10, EMAIL), _condition(20)),
+ _flag(_condition(50, EMAIL)),
+ {ROLLOUT_INCREASED, CONDITION_REMOVED},
+ RAISES,
+ ),
+ ]
+ )
+ def test_classifies_the_edit(
+ self,
+ _name: str,
+ before: FlagExposureConfig,
+ after: FlagExposureConfig,
+ kinds: set[ExposureChangeKind],
+ direction: ExposureDirection,
+ ) -> None:
+ change = classify_exposure_change(before=before, after=after)
+
+ assert change.kinds == kinds
+ assert change.direction == direction
+
+ @parameterized.expand(
+ [
+ (
+ "split_and_overrides",
+ _flag(_condition(100, EMAIL, variant="b"), _condition(100), variants=SPLIT_ALL_A),
+ ("a", "b"),
+ ),
+ (
+ "every_condition_has_an_override",
+ _flag(_condition(100, EMAIL, variant="b"), variants=SPLIT_ALL_A),
+ ("b",),
+ ),
+ ("variant_at_zero_percent", _flag(_condition(100), variants=SPLIT_ALL_A), ("a",)),
+ (
+ "override_of_a_condition_at_zero_rollout",
+ _flag(_condition(0, EMAIL, variant="b"), _condition(100), variants=SPLIT_ALL_A),
+ ("a",),
+ ),
+ (
+ "split_drawn_only_by_a_condition_at_zero_rollout",
+ _flag(_condition(0), _condition(100, EMAIL, variant="b"), variants=SPLIT_50_50),
+ ("b",),
+ ),
+ (
+ "disabled",
+ _flag(_condition(100, EMAIL, variant="b"), _condition(100), variants=SPLIT_ALL_A, active=False),
+ (),
+ ),
+ ("boolean_flag_with_a_leftover_override", _flag(_condition(100, variant="b")), ()),
+ ("deleted", _flag(_condition(100), variants=SPLIT_ALL_A, deleted=True), ()),
+ ]
+ )
+ def test_lists_the_variants_that_the_flag_serves(
+ self, _name: str, after: FlagExposureConfig, served_variants: tuple[str, ...]
+ ) -> None:
+ change = classify_exposure_change(before=_flag(_condition(100), variants=SPLIT_ALL_A), after=after)
+
+ assert change.served_variants == served_variants
+
+ @parameterized.expand(
+ [
+ ("before", VERSION_2, _flag(_condition(50))),
+ ("after", _flag(_condition(50)), VERSION_2),
+ ]
+ )
+ def test_refuses_a_version_2_config(
+ self, _name: str, before: FlagExposureConfig, after: FlagExposureConfig
+ ) -> None:
+ with self.assertRaises(ConfigFormatError):
+ classify_exposure_change(before=before, after=after)