feat(experimentation): default to control when rollout segment is created

api/experimentation/services.py

@@ -42,6 +42,7 @@
 )
 from experimentation.models import (
     VALID_STATUS_TRANSITIONS,
+    Experiment,
     ExperimentStatus,
     MetricAggregation,
     MetricDirection,
@@ -57,22 +58,29 @@
 )
 from features.models import FeatureState
 from features.value_types import BOOLEAN, INTEGER, STRING
-from features.versioning.dataclasses import FlagChangeSet
+from features.versioning.dataclasses import FlagChangeSet, MultivariateValueChangeSet
 from features.versioning.versioning_service import (
+    get_environment_flags_list,
     update_flag,
     update_multivariate_values,
 )
 from integrations.flagsmith.client import get_openfeature_client
 from segments.models import Condition, Segment, SegmentRule
 
-_ROLLOUT_VALUE_TYPE = {INTEGER: "integer", STRING: "string", BOOLEAN: "boolean"}
+_ROLLOUT_VALUE_TYPE: dict[str, "FeatureValueType"] = {
+    INTEGER: "integer",
+    STRING: "string",
+    BOOLEAN: "boolean",
+}
 
 if typing.TYPE_CHECKING:
     from collections.abc import Sequence
     from datetime import datetime
 
-    from experimentation.models import Experiment, Metric, WarehouseConnection
+    from experimentation.models import Metric, WarehouseConnection
     from experimentation.types import ExposureGranularity
+    from features.feature_states.models import FeatureValueType
+    from features.models import FeatureStateValue
     from organisations.models import Organisation
     from users.models import FFAdminUser
 
@@ -579,18 +587,15 @@ def _sync_rollout_segment(experiment: Experiment, rollout_percentage: float) ->
 
 
 def _get_live_rollout_override(experiment: Experiment) -> FeatureState | None:
-    return (
-        FeatureState.objects.get_live_feature_states(
-            environment=experiment.environment,
-            additional_filters=Q(
-                feature_segment__segment_id=experiment.rollout_segment_id,
-                identity__isnull=True,
-            ),
+    flags = get_environment_flags_list(
+        environment=experiment.environment,
+        additional_filters=Q(
             feature_id=experiment.feature_id,
-        )
-        .order_by("-id")
-        .first()
+            feature_segment__segment_id=experiment.rollout_segment_id,
+            identity__isnull=True,
+        ),
     )
+    return flags[0] if flags else None
 
 
 def _update_live_feature_state(
@@ -627,15 +632,60 @@ def _update_rollout_in_place(experiment: Experiment, change_set: FlagChangeSet)
     update_flag(experiment.environment, experiment.feature, change_set)
 
 
+def _reset_default_allocations_to_control(
+    experiment: Experiment, author: AuthorData
+) -> None:
+    """Zero every variant's allocation on the feature's environment-default
+    feature state, leaving control (the unallocated remainder) at 100%.
+
+    Run once, when the rollout segment is first created: identities outside the
+    rollout cohort should all receive control while the experiment runs.
+    """
+    (default_state,) = get_environment_flags_list(
+        environment=experiment.environment,
+        additional_filters=Q(
+            feature_id=experiment.feature_id,
+            feature_segment__isnull=True,
+            identity__isnull=True,
+        ),
+    )
+    str_value, value_type = _serialize_feature_state_value(
+        default_state.feature_state_value
+    )
+    update_flag(
+        experiment.environment,
+        experiment.feature,
+        FlagChangeSet(
+            author=author,
+            enabled=default_state.enabled,
+            feature_state_value=str_value,
+            type_=value_type,
+            multivariate_values=[
+                MultivariateValueChangeSet(
+                    multivariate_feature_option_id=option_id,
+                    percentage_allocation=0,
+                )
+                for option_id in experiment.feature.multivariate_options.values_list(
+                    "id", flat=True
+                )
+            ],
+        ),
+    )
+
+
 def apply_experiment_rollout(experiment: Experiment, spec: RolloutSpec) -> None:
-    if experiment.status == ExperimentStatus.COMPLETED:
-        raise ValidationError(
-            f"Cannot change the rollout of a {experiment.status} experiment."
-        )
     validate_rollout_spec(experiment, spec)
     environment_id = experiment.environment_id
     with transaction.atomic():
+        experiment.refresh_from_db(from_queryset=Experiment.objects.select_for_update())
+        if experiment.status == ExperimentStatus.COMPLETED:
+            raise ValidationError(
+                f"Cannot change the rollout of a {experiment.status} experiment."
+            )
+        is_first_rollout = experiment.rollout_segment_id is None
         segment = _sync_rollout_segment(experiment, spec.rollout_percentage)
+        if is_first_rollout:
+            _reset_default_allocations_to_control(experiment, spec.author)
         _update_rollout_in_place(
             experiment,
             FlagChangeSet(
@@ -655,6 +705,19 @@ def apply_experiment_rollout(experiment: Experiment, spec: RolloutSpec) -> None:
         )
 
 
+def _serialize_feature_state_value(
+    value: FeatureStateValue,
+) -> tuple[str, FeatureValueType]:
+    """Render a stored feature state value as the (string, API type) pair that
+    a `FlagChangeSet` expects."""
+    if value.value is None:
+        return "", "string"
+    return (
+        str(value.value).lower() if value.type == BOOLEAN else str(value.value),
+        _ROLLOUT_VALUE_TYPE.get(value.type or STRING, "string"),
+    )
+
+
 def get_experiment_rollout(experiment: Experiment) -> dict[str, typing.Any] | None:
     segment_id = experiment.rollout_segment_id
     if segment_id is None:
@@ -671,16 +734,13 @@ def get_experiment_rollout(experiment: Experiment) -> dict[str, typing.Any] | No
     condition = Condition.objects.get(
         rule__segment_id=segment_id, operator=PERCENTAGE_SPLIT
     )
-    value = feature_state.feature_state_value
+    str_value, value_type = _serialize_feature_state_value(
+        feature_state.feature_state_value
+    )
     return {
         "enabled": feature_state.enabled,
         "rollout_percentage": float(condition.value or 0),
-        "feature_state_value": {
-            "type": _ROLLOUT_VALUE_TYPE.get(value.type or STRING, "string"),
-            "value": (
-                str(value.value).lower() if value.type == BOOLEAN else str(value.value)
-            ),
-        },
+        "feature_state_value": {"type": value_type, "value": str_value},
         "multivariate_feature_state_values": [
             {
                 "multivariate_feature_option": mv.multivariate_feature_option_id,

api/tests/unit/experimentation/test_experiment_views.py

@@ -6,6 +6,7 @@
 
 import pytest
 from django.db import IntegrityError
+from django.db.models import Q
 from django.urls import reverse
 from django.utils import timezone
 from freezegun import freeze_time
@@ -1926,6 +1927,135 @@ def test_post__with_experiment_rollout__creates_rollout(
     assert experiment.rollout_segment.is_system_segment is True
 
 
+def test_post__with_experiment_rollout__zeroes_default_allocations(
+    admin_client_new: APIClient,
+    environment: Environment,
+    multivariate_feature: Feature,
+    multivariate_options: list[MultivariateFeatureOption],
+    enable_features: EnableFeaturesFixture,
+) -> None:
+    # Given
+    enable_features(EXPERIMENT_FLAG)
+    option_a, option_b, option_c = multivariate_options
+
+    # When
+    response = admin_client_new.post(
+        _list_url(environment),
+        data={
+            "feature": multivariate_feature.id,
+            "name": "Rollout experiment",
+            "hypothesis": "It will work",
+            "experiment_rollout": {
+                "enabled": True,
+                "rollout_percentage": 30,
+                "feature_state_value": {"type": "string", "value": "control"},
+                "multivariate_feature_state_values": [
+                    {
+                        "multivariate_feature_option": option_a.id,
+                        "percentage_allocation": 60,
+                    },
+                    {
+                        "multivariate_feature_option": option_b.id,
+                        "percentage_allocation": 40,
+                    },
+                ],
+            },
+        },
+        format="json",
+    )
+
+    # Then
+    assert response.status_code == status.HTTP_201_CREATED
+    experiment = Experiment.objects.get(id=response.json()["id"])
+    env_default_state = FeatureState.objects.get(
+        feature=multivariate_feature,
+        environment=environment,
+        identity__isnull=True,
+        feature_segment__isnull=True,
+    )
+    default_allocations = {
+        mv.multivariate_feature_option_id: mv.percentage_allocation
+        for mv in env_default_state.multivariate_feature_state_values.all()
+    }
+    assert default_allocations == {option_a.id: 0, option_b.id: 0, option_c.id: 0}
+
+    # The rollout segment override keeps the experiment's own split.
+    override = FeatureState.objects.get(
+        feature=multivariate_feature,
+        environment=environment,
+        feature_segment__segment=experiment.rollout_segment,
+    )
+    override_allocations = {
+        mv.multivariate_feature_option_id: mv.percentage_allocation
+        for mv in override.multivariate_feature_state_values.all()
+    }
+    assert override_allocations == {option_a.id: 60.0, option_b.id: 40.0}
+
+
+def test_post__with_experiment_rollout_v2_versioning__zeroes_default_allocations(
+    admin_client_new: APIClient,
+    environment_v2_versioning: Environment,
+    multivariate_feature: Feature,
+    multivariate_options: list[MultivariateFeatureOption],
+    enable_features: EnableFeaturesFixture,
+) -> None:
+    # Given
+    enable_features(EXPERIMENT_FLAG)
+    option_a, option_b, option_c = multivariate_options
+
+    # When
+    response = admin_client_new.post(
+        _list_url(environment_v2_versioning),
+        data={
+            "feature": multivariate_feature.id,
+            "name": "Rollout experiment",
+            "hypothesis": "It will work",
+            "experiment_rollout": {
+                "enabled": True,
+                "rollout_percentage": 30,
+                "feature_state_value": {"type": "string", "value": "control"},
+                "multivariate_feature_state_values": [
+                    {
+                        "multivariate_feature_option": option_a.id,
+                        "percentage_allocation": 60,
+                    },
+                    {
+                        "multivariate_feature_option": option_b.id,
+                        "percentage_allocation": 40,
+                    },
+                ],
+            },
+        },
+        format="json",
+    )
+
+    # Then the live environment default has its allocations zeroed
+    assert response.status_code == status.HTTP_201_CREATED
+    experiment = Experiment.objects.get(id=response.json()["id"])
+    env_default_state = FeatureState.objects.get_live_feature_states(
+        environment=environment_v2_versioning,
+        additional_filters=Q(feature_segment__isnull=True, identity__isnull=True),
+        feature_id=multivariate_feature.id,
+    ).latest("id")
+    default_allocations = {
+        mv.multivariate_feature_option_id: mv.percentage_allocation
+        for mv in env_default_state.multivariate_feature_state_values.all()
+    }
+    assert default_allocations == {option_a.id: 0, option_b.id: 0, option_c.id: 0}
+
+    # and the live rollout segment override keeps the experiment's own split
+    override = FeatureState.objects.get_live_feature_states(
+        environment=environment_v2_versioning,
+        additional_filters=Q(feature_segment__segment=experiment.rollout_segment),
+        feature_id=multivariate_feature.id,
+    ).latest("id")
+    override_allocations = {
+        mv.multivariate_feature_option_id: mv.percentage_allocation
+        for mv in override.multivariate_feature_state_values.all()
+    }
+    assert override_allocations == {option_a.id: 60.0, option_b.id: 40.0}
+
+
 def test_post__rollout_allocations_exceed_100__returns_400(
     admin_client_new: APIClient,
     environment: Environment,