feat(dashboards): Store dashboard snapshot on PUT when revisions flag is enabled

When the organizations:dashboards-revisions feature flag is enabled, the
dashboard PUT endpoint now serializes the current dashboard state (using
the existing DashboardDetailsModelSerializer) into a DashboardRevision
before writing the new version. The snapshot and the save are wrapped in
the same transaction so a failed update rolls back the revision too.

Serialization is intentionally done outside the transaction to avoid
making hybrid-cloud RPC calls (user_service.serialize_many) inside an
atomic block.

Revisions beyond the 10 most recent are deleted after each save to
bound storage growth.

Refs DAIN-1516
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: skaasten

src/sentry/dashboards/endpoints/organization_dashboard_details.py

@@ -30,13 +30,17 @@
     Dashboard,
     DashboardFavoriteUser,
     DashboardLastVisited,
+    DashboardRevision,
     DashboardTombstone,
 )
 from sentry.models.organization import Organization
 from sentry.models.organizationmember import OrganizationMember
 
 EDIT_FEATURE = "organizations:dashboards-edit"
 READ_FEATURE = "organizations:dashboards-basic"
+REVISIONS_FEATURE = "organizations:dashboards-revisions"
+DASHBOARD_REVISION_SNAPSHOT_SCHEMA_VERSION = 1
+DASHBOARD_REVISION_RETENTION_LIMIT = 10
 
 
 class OrganizationDashboardBase(OrganizationEndpoint):
@@ -208,8 +212,32 @@ def put(
                     {"detail": "Cannot change the title of prebuilt Dashboards."}, status=409
                 )
 
+        # Serialize outside the transaction to avoid making RPC calls inside a transaction.
+        # The snapshot captures the dashboard state before the update is applied.
+        create_revision = features.has(
+            REVISIONS_FEATURE, organization, actor=request.user
+        ) and isinstance(dashboard, Dashboard)
+        snapshot = serialize(dashboard, request.user) if create_revision else None
+
         try:
             with transaction.atomic(router.db_for_write(DashboardTombstone)):
+                if create_revision and snapshot is not None:
+                    revision = DashboardRevision.objects.create(
+                        dashboard=dashboard,
+                        created_by_id=(request.user.id if request.user.is_authenticated else None),
+                        title=dashboard.title,
+                        snapshot=snapshot,
+                        snapshot_schema_version=DASHBOARD_REVISION_SNAPSHOT_SCHEMA_VERSION,
+                    )
+                    # Keep only the most recent revisions; delete the rest
+                    old_revision_ids = list(
+                        DashboardRevision.objects.filter(dashboard=dashboard)
+                        .exclude(id=revision.id)
+                        .order_by("-date_added")
+                        .values_list("id", flat=True)[DASHBOARD_REVISION_RETENTION_LIMIT - 1 :]
+                    )
+                    if old_revision_ids:
+                        DashboardRevision.objects.filter(id__in=old_revision_ids).delete()
                 serializer.save()
                 if tombstone:
                     DashboardTombstone.objects.get_or_create(

tests/sentry/dashboards/endpoints/test_organization_dashboard_details.py

@@ -16,6 +16,7 @@
     Dashboard,
     DashboardFavoriteUser,
     DashboardLastVisited,
+    DashboardRevision,
     DashboardTombstone,
 )
 from sentry.models.dashboard_permissions import DashboardPermissions
@@ -4012,6 +4013,118 @@ def test_text_widget_errors_provided_queries(self) -> None:
             assert "queries" in response.data["widgets"][1], response.data
             assert response.data["widgets"][1]["queries"][0] == "Text widgets don't have queries"
 
+    def test_put_creates_dashboard_revision_when_feature_enabled(self) -> None:
+        original_title = self.dashboard.title
+        with self.feature("organizations:dashboards-revisions"):
+            response = self.do_request(
+                "put", self.url(self.dashboard.id), data={"title": "Updated Title"}
+            )
+        assert response.status_code == 200, response.data
+
+        revisions = DashboardRevision.objects.filter(dashboard=self.dashboard)
+        assert revisions.count() == 1
+        revision = revisions.first()
+        assert revision is not None
+        assert revision.title == original_title
+        assert revision.snapshot["title"] == original_title
+        assert revision.snapshot_schema_version == 1
+        assert revision.created_by_id == self.user.id
+
+    def test_put_does_not_create_revision_when_feature_disabled(self) -> None:
+        response = self.do_request(
+            "put", self.url(self.dashboard.id), data={"title": "Updated Title"}
+        )
+        assert response.status_code == 200, response.data
+        assert DashboardRevision.objects.filter(dashboard=self.dashboard).count() == 0
+
+    def test_put_snapshot_contains_pre_save_state(self) -> None:
+        with self.feature("organizations:dashboards-revisions"):
+            self.do_request("put", self.url(self.dashboard.id), data={"title": "New Title"})
+
+        revision = DashboardRevision.objects.get(dashboard=self.dashboard)
+        # Snapshot reflects the state before the update
+        assert revision.snapshot["title"] == self.dashboard.title
+        assert revision.title == self.dashboard.title
+        # The dashboard itself was updated
+        self.dashboard.refresh_from_db()
+        assert self.dashboard.title == "New Title"
+
+    def test_put_deletes_revisions_beyond_retention_limit(self) -> None:
+        # Create 10 existing revisions
+        for i in range(10):
+            DashboardRevision.objects.create(
+                dashboard=self.dashboard,
+                created_by_id=self.user.id,
+                title=f"Revision {i}",
+                snapshot={},
+                snapshot_schema_version=1,
+            )
+
+        assert DashboardRevision.objects.filter(dashboard=self.dashboard).count() == 10
+
+        with self.feature("organizations:dashboards-revisions"):
+            response = self.do_request(
+                "put", self.url(self.dashboard.id), data={"title": "Updated Title"}
+            )
+        assert response.status_code == 200, response.data
+
+        # After creating the 11th revision, the oldest should be deleted to maintain 10
+        assert DashboardRevision.objects.filter(dashboard=self.dashboard).count() == 10
+
+    def test_put_snapshot_includes_widgets_and_queries(self) -> None:
+        with self.feature("organizations:dashboards-revisions"):
+            self.do_request("put", self.url(self.dashboard.id), data={"title": "New Title"})
+
+        revision = DashboardRevision.objects.get(dashboard=self.dashboard)
+        snapshot_widgets = revision.snapshot["widgets"]
+
+        assert len(snapshot_widgets) == 4
+        assert snapshot_widgets[0]["id"] == str(self.widget_1.id)
+        assert snapshot_widgets[0]["title"] == self.widget_1.title
+        assert len(snapshot_widgets[0]["queries"]) == 2
+        assert snapshot_widgets[1]["id"] == str(self.widget_2.id)
+        assert snapshot_widgets[1]["title"] == self.widget_2.title
+        assert len(snapshot_widgets[1]["queries"]) == 1
+        assert snapshot_widgets[2]["id"] == str(self.widget_3.id)
+        assert snapshot_widgets[3]["id"] == str(self.widget_4.id)
+
+    def test_put_snapshot_captures_widget_state_before_widget_edit(self) -> None:
+        original_widget_title = self.widget_1.title
+        with self.feature("organizations:dashboards-revisions"):
+            self.do_request(
+                "put",
+                self.url(self.dashboard.id),
+                data={
+                    "title": self.dashboard.title,
+                    "widgets": [
+                        {"id": str(self.widget_1.id), "title": "Updated Widget Title"},
+                        {"id": str(self.widget_2.id)},
+                        {"id": str(self.widget_3.id)},
+                        {"id": str(self.widget_4.id)},
+                    ],
+                },
+            )
+
+        revision = DashboardRevision.objects.get(dashboard=self.dashboard)
+        snapshot_widget = revision.snapshot["widgets"][0]
+        # Snapshot reflects the widget state before the edit
+        assert snapshot_widget["id"] == str(self.widget_1.id)
+        assert snapshot_widget["title"] == original_widget_title
+        # The widget itself was updated
+        self.widget_1.refresh_from_db()
+        assert self.widget_1.title == "Updated Widget Title"
+
+    def test_put_does_not_create_revision_for_prebuilt_tombstone(self) -> None:
+        with self.feature("organizations:dashboards-revisions"):
+            response = self.do_request(
+                "put",
+                self.url("default-overview"),
+                data={"title": "default-overview"},
+            )
+        assert response.status_code == 200, response.data
+        # No revision should be created for a pre-built dashboard that hasn't been saved yet
+        assert DashboardRevision.objects.count() == 0
+
 
 class OrganizationDashboardDetailsOnDemandTest(OrganizationDashboardDetailsTestCase):
     widget_type = DashboardWidgetTypes.TRANSACTION_LIKE