Clarify annotations migration

Author: apata

priv/repo/migrations/20260421101200_create_annotations.exs

@@ -12,15 +12,27 @@ defmodule Plausible.Repo.Migrations.CreateAnnotations do
       "DROP TYPE annotation_granularity"
     )
 
+    # Example annotations
+    #
+    # id |            note             | granularity |      datetime
+    # ---+-----------------------------+-------------+--------------------
+    #  1 | Christmas sale              | date        | 2025-12-14 00:00:00
+    #  2 | Released feature X          | minute      | 2026-05-08 14:00:00
+    #
+    # Depending on granularity, the datetime must be interpreted in a different way:
+    #
+    # For granularity "date", only the date part of the `datetime` is meaningful.
+    # The annotation is on that particular calendar date, no matter the timezone.
+    # We store it as midnight, 00:00:00, but we could just as well store it as 13:37:00:
+    # the time must be ignored by the server.
+    #
+    # For granularity "time", all of the datetime is meaningful.
+    # The annotation is at that particular point in time. It's stored as UTC timestamp (naive)
+    # and must be shifted to the site timezone.
+
     create table(:annotations) do
       add :note, :string, null: false
       add :type, :annotation_type, null: false, default: "personal"
-      # UTC datetime. The local date/time is derived by the frontend using the
-      # site's configured timezone at display time.
-      # granularity='date'   — caller provides UTC midnight of the intended local date;
-      #                        only the date component is shown.
-      # granularity='minute' — caller provides the exact UTC moment;
-      #                        both date and HH:MM are shown in site-local time.
       add :datetime, :utc_datetime, null: false
       add :granularity, :annotation_granularity, null: false
       add :site_id, references(:sites, on_delete: :delete_all), null: false