From 71211e572212f84fd62921b8c90d8590ec235cf0 Mon Sep 17 00:00:00 2001
From: atlas <atlas@hyperhive>
Date: Sat, 30 May 2026 20:50:17 +0200
Subject: [PATCH] nix/matrix: add breaking-change note to serverName
 description (argus #661)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

argus on #661 🟡: "matrix IDs embed server_name irrevocably — anyone
already running with the old default would be broken."

Append a `**Breaking change as of #660**` paragraph to the
`serverName` option description with the exact opt-back-in string,
matching the pattern from #651's openFirewall flip. PR body + commit
already documented the breakage; this surfaces it in the option's
own description so it shows up in `nix flake show` + the auto-
generated options docs right next to the option.
---
 nix/modules/hive-matrix.nix | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/nix/modules/hive-matrix.nix b/nix/modules/hive-matrix.nix
index 5903b5a2..c1575d9e 100644
--- a/nix/modules/hive-matrix.nix
+++ b/nix/modules/hive-matrix.nix
@@ -84,6 +84,13 @@ in
         different server_name shape (e.g. `matrix.<domain>` if you
         want the subdomain split, or `chat.example.org` for a
         bespoke hostname).
+
+        **Breaking change as of #660**: this used to default to
+        `matrix.''${services.hyperhive.domain}`. matrix IDs embed
+        the server_name irrevocably, so existing homeservers must
+        set `services.hyperhive.matrix.serverName = "matrix.''${services.hyperhive.domain}";`
+        explicitly to preserve their pre-#660 user / room IDs
+        before rebuilding.
       '';
     };