Skip to content
Open
10 changes: 10 additions & 0 deletions api/experimentation/dataclasses.py
Original file line number Diff line number Diff line change
@@ -1,12 +1,16 @@
from dataclasses import dataclass
from datetime import datetime
from typing import TYPE_CHECKING

from core.dataclasses import AuthorData
from experimentation.stats import Inference, VariantStats
from experimentation.types import ExposureGranularity
from features.feature_states.models import FeatureValueType
from features.future.types import Variant

if TYPE_CHECKING:
from experimentation.models import RolloutDecision


@dataclass(frozen=True)
class AudienceSpec:
Expand All @@ -25,6 +29,12 @@ class RolloutSpec:
audience: AudienceSpec | None = None


@dataclass(frozen=True)
class RolloutDecisionSpec:
decision: "RolloutDecision"
rollout_variant_id: int | None = None


@dataclass(frozen=True)
class WarehouseEventStats:
total_events_received: int
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# Generated by Django 5.2.18 on 2026-11-19 11:45

import django.db.models.deletion
from django.db import migrations, models


class Migration(migrations.Migration):
dependencies = [
("experimentation", "0019_add_sdk_experimentation_event"),
("multivariate", "0009_add_multivariate_feature_option_key"),
]

operations = [
migrations.AddField(
model_name="experiment",
name="rollout_decision",
field=models.CharField(
blank=True,
choices=[
("control", "Control"),
("variant", "Variant"),
("disable", "Disable"),
],
max_length=50,
null=True,
),
),
migrations.AddField(
model_name="experiment",
name="rollout_variant",
field=models.ForeignKey(
blank=True,
null=True,
on_delete=django.db.models.deletion.SET_NULL,
related_name="+",
to="multivariate.multivariatefeatureoption",
),
),
]
19 changes: 19 additions & 0 deletions api/experimentation/models.py
Original file line number Diff line number Diff line change
Expand Up @@ -140,6 +140,12 @@ class ExperimentStatus(models.TextChoices):
COMPLETED = "completed", "Completed"


class RolloutDecision(models.TextChoices):
CONTROL = "control", "Control"
VARIANT = "variant", "Variant"
DISABLE = "disable", "Disable"


class AudienceMatch(models.TextChoices):
ANY = "any", "Any"
ALL = "all", "All"
Expand Down Expand Up @@ -175,6 +181,19 @@ class Experiment(LifecycleModelMixin, SoftDeleteExportableModel): # type: ignor
updated_at = models.DateTimeField(auto_now=True)
started_at = models.DateTimeField(null=True, blank=True)
ended_at = models.DateTimeField(null=True, blank=True)
rollout_decision = models.CharField(
max_length=50,
choices=RolloutDecision.choices,
null=True,
blank=True,
)
rollout_variant = models.ForeignKey(
"multivariate.MultivariateFeatureOption",
on_delete=models.SET_NULL,

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: on_delete=SET_NULL clears rollout_variant when the variant is deleted, but rollout_decision stays variant. A completed experiment then reports a variant decision with no variant, so the record no longer shows which variant won. Decide whether this is intended; if not, clear rollout_decision when the variant is removed, or block variant deletion while a completed experiment references it.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At api/experimentation/models.py, line 192:

<comment>`on_delete=SET_NULL` clears `rollout_variant` when the variant is deleted, but `rollout_decision` stays `variant`. A completed experiment then reports a `variant` decision with no variant, so the record no longer shows which variant won. Decide whether this is intended; if not, clear `rollout_decision` when the variant is removed, or block variant deletion while a completed experiment references it.</comment>

<file context>
@@ -175,6 +181,19 @@ class Experiment(LifecycleModelMixin, SoftDeleteExportableModel):  # type: ignor
+    )
+    rollout_variant = models.ForeignKey(
+        "multivariate.MultivariateFeatureOption",
+        on_delete=models.SET_NULL,
+        related_name="+",
+        null=True,
</file context>

related_name="+",
null=True,
blank=True,
)
rollout_segment = models.OneToOneField(
"segments.Segment",
on_delete=models.SET_NULL,
Expand Down
39 changes: 39 additions & 0 deletions api/experimentation/serializers.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@
)
from experimentation.dataclasses import (
AudienceSpec,
RolloutDecisionSpec,
RolloutSpec,
WarehouseEventStats,
)
Expand All @@ -27,6 +28,7 @@
ExperimentStatus,
Metric,
MetricDirection,
RolloutDecision,
WarehouseConnection,
WarehouseConnectionStatus,
WarehouseType,
Expand Down Expand Up @@ -313,6 +315,39 @@ def to_spec(data: dict[str, Any], request: Any) -> RolloutSpec:
)


class ExperimentRolloutDecisionSerializer(serializers.Serializer): # type: ignore[type-arg]
rollout_decision = serializers.ChoiceField(choices=RolloutDecision.choices)
rollout_variant = serializers.IntegerField(required=False)

def validate(self, attrs: dict[str, Any]) -> dict[str, Any]:
experiment: Experiment = self.context["experiment"]
rollout_variant: int | None = attrs.get("rollout_variant")
if attrs["rollout_decision"] != RolloutDecision.VARIANT:
if rollout_variant is not None:
raise serializers.ValidationError(
{"rollout_variant": "Only allowed when rolling out a variant."}
)
return attrs
if rollout_variant is None:
raise serializers.ValidationError(
{"rollout_variant": "Required when rolling out a variant."}
)
if not experiment.feature.multivariate_options.filter(
id=rollout_variant
).exists():
raise serializers.ValidationError(
{"rollout_variant": "Variant not found for the experiment's feature."}
)
return attrs

@staticmethod
def to_spec(data: dict[str, Any]) -> RolloutDecisionSpec:
return RolloutDecisionSpec(
decision=data["rollout_decision"],
rollout_variant_id=data.get("rollout_variant"),
)


class ExperimentSerializer(serializers.ModelSerializer): # type: ignore[type-arg]
# Annotated with the common base type so ExperimentListSerializer can
# override the field with a read-only representation.
Expand All @@ -339,6 +374,8 @@ class Meta:
"updated_at",
"started_at",
"ended_at",
"rollout_decision",
"rollout_variant",
)
read_only_fields = (
"id",
Expand All @@ -347,6 +384,8 @@ class Meta:
"updated_at",
"started_at",
"ended_at",
"rollout_decision",
"rollout_variant",
)

def validate_feature(self, feature: Any) -> Any:
Expand Down
89 changes: 88 additions & 1 deletion api/experimentation/services.py
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@
MetricSpec,
ResultsAggregates,
ResultsSummary,
RolloutDecisionSpec,
RolloutSpec,
WarehouseEventNames,
WarehouseEventStats,
Expand All @@ -58,6 +59,7 @@
ExperimentStatus,
MetricAggregation,
MetricDirection,
RolloutDecision,
SDKExperimentationEvent,
WarehouseConnection,
WarehouseConnectionStatus,
Expand All @@ -78,7 +80,7 @@
from features.feature_segments.services import get_next_segment_override_priority
from features.feature_states.models import API_VALUE_TYPES
from features.future.services import delete_segment_override, update_flag
from features.future.types import SegmentOverrideRequest
from features.future.types import EnvironmentDefaultRequest, SegmentOverrideRequest
from features.models import FeatureState
from features.value_types import BOOLEAN, STRING
from features.versioning.versioning_service import get_environment_flags_list
Expand Down Expand Up @@ -606,6 +608,8 @@ def transition_experiment_status(
experiment: Experiment,
target_status: str,
user: FFAdminUser,
*,
rollout_decision: RolloutDecisionSpec | None = None,
) -> Experiment:
with transaction.atomic():
experiment.refresh_from_db(from_queryset=Experiment.objects.select_for_update())
Expand All @@ -622,13 +626,96 @@ def transition_experiment_status(
experiment, AuthorData.from_user(user)
)
elif target_status == ExperimentStatus.COMPLETED:
if rollout_decision is None:
raise ValueError(
"Cannot complete an experiment without a rollout decision."
)
experiment.ended_at = timezone.now()
experiment.rollout_decision = rollout_decision.decision
experiment.rollout_variant_id = rollout_decision.rollout_variant_id
_apply_rollout_decision(
experiment, rollout_decision, AuthorData.from_user(user)
)
transaction.on_commit(
lambda: experimentation_logger.info(
"experiment.completed",
experiment__id=experiment.id,
environment__id=experiment.environment_id,
feature__id=experiment.feature_id,
rollout__decision=rollout_decision.decision,
variant__id=rollout_decision.rollout_variant_id,
)
)

experiment.save()
create_experiment_audit_log(experiment, user, action=target_status)
return experiment


def delete_experiment(experiment: Experiment, user: FFAdminUser) -> None:
with transaction.atomic():
experiment.refresh_from_db(from_queryset=Experiment.objects.select_for_update())
if experiment.status == ExperimentStatus.RUNNING:
raise ValueError(
"Cannot delete a running experiment. Pause or complete it first."
)
_delete_experiment_rollout_override(experiment, AuthorData.from_user(user))
create_experiment_audit_log(experiment, user, action="deleted")
experiment.delete()


def _apply_rollout_decision(
experiment: Experiment,
rollout_decision: RolloutDecisionSpec,
author: AuthorData,
) -> None:
"""Serve the decided outcome from the environment default and remove the
rollout override. The rollout segment is kept: it records the audience."""
environment_default: EnvironmentDefaultRequest = (
{"enabled": False}
if rollout_decision.decision == RolloutDecision.DISABLE
else {
"enabled": True,

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Major · Functional Correctness · Quick win

Carry the rollout's control value into the environment default on control completion.

The rollout override stores its own control value from the request (feature_state_value). The serializer does not compare that value with the environment default. A control completion sends an environment default payload with no value, so the default keeps its existing value. After the rollout override is deleted, control identities receive that default value. A rollout value of "B" with a default of "A" therefore changes the control outcome to "A" without any recorded change.

Before deleting the override, read its control value and write that value to the environment default. Alternatively, reject completion when the two values differ. Either way, identities in the control arm must keep the value they received during the experiment.

"variants": [
{
"id": option_id,
"weight": (
100 if option_id == rollout_decision.rollout_variant_id else 0
),
}
for option_id in experiment.feature.multivariate_options.values_list(
"id", flat=True
)
],
}
)
update_flag(
environment=experiment.environment,
feature=experiment.feature,
changes={"environment_default": environment_default},
replace=False,
author=author,
overwrite_system_segment_overrides=True,
)
_delete_experiment_rollout_override(experiment, author)


def _delete_experiment_rollout_override(
experiment: Experiment, author: AuthorData
) -> None:
if (
segment_id := experiment.rollout_segment_id
) is None or not _get_live_rollout_override(experiment):
return
delete_segment_override(
environment=experiment.environment,
feature=experiment.feature,
segment_id=segment_id,
author=author,
overwrite_system_segment_overrides=True,
)


def _remove_superseded_experiment_rollouts(
experiment: Experiment, author: AuthorData
) -> None:
Expand Down
Loading
Loading