From 47f5e57c6857ab9af6edff5ef8c59a4c2ab0a788 Mon Sep 17 00:00:00 2001 From: iris Date: Wed, 19 Aug 2026 19:55:21 +0200 Subject: [PATCH 1/2] docs(matrix): demote breaking-change notes to clearly-scoped upgrade sections MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit serverName/gatewayHost and openFirewall both led with 'Breaking change'/'has now moved twice' phrasing woven into the primary explanation, reading as an active/ongoing concern rather than settled current behaviour with a historical upgrade note attached. Reframed to state the current default first, then a demarcated 'Upgrading...' section/note for deployments carrying an older value forward — same pattern swarm/README.md's own upgrade notes already use. No factual content changed, removed, or added. --- docs/matrix.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/docs/matrix.md b/docs/matrix.md index 5bc4328e..734bef4b 100644 --- a/docs/matrix.md +++ b/docs/matrix.md @@ -41,7 +41,7 @@ Two distinct hostnames: `chat.`. Set to `null` to skip the gateway vhost (tuwunel stays direct on `httpPort`). -Both now default under the **swarm** domain, because a swarm runs one +Both default under the **swarm** domain, because a swarm runs one homeserver: tying its identity to a single hive's domain would make relocating the container between hives look like a different homeserver. @@ -54,10 +54,14 @@ adopting a new one does **not** rename the existing users and rooms — it strands them, because their ids still name a homeserver that no longer answers. -**Breaking change — pin `serverName` before rebuilding.** Its default -has now moved twice: from `matrix.${services.hyperhive.domain}`, to -the bare hive domain, and now to the swarm domain. Any homeserver that -has already minted ids must name the value it minted them under: +### Upgrading a homeserver that already has ids + +`serverName`'s default has changed across releases (from +`matrix.${services.hyperhive.domain}`, to the bare hive domain, to the +current swarm domain). A homeserver that has already minted ids under +an older default must **pin the value it actually minted them +under**, not adopt the new default — see above for why adopting a new +one strands existing users and rooms: ```nix services.hyperhive.swarm.matrix = { @@ -82,9 +86,9 @@ matters for access from *outside* the host. Flip to `true` when announcing the homeserver to other hives or when an external matrix client needs to reach the client-server API directly. -**Breaking change**: used to default to `true`. Operators relying on -external reach must add -`services.hyperhive.swarm.matrix.openFirewall = true;` before rebuilding. +**Upgrading:** earlier releases defaulted `openFirewall` to `true`. +Operators relying on external reach need to add +`services.hyperhive.swarm.matrix.openFirewall = true;` explicitly now. Federation port 8448 is intentionally not opened here — tuwunel serves the federation API on the same `httpPort` as client-server From 149f745e76a887de8a6848ce5c003048bb87574e Mon Sep 17 00:00:00 2001 From: iris Date: Wed, 19 Aug 2026 20:01:45 +0200 Subject: [PATCH 2/2] docs(matrix): trim upgrade notes per review - serverName upgrade note: state that it changed, drop the historical list of what it changed from/to - openFirewall upgrade note: remove entirely, change is old enough that it's no longer worth flagging --- docs/matrix.md | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/docs/matrix.md b/docs/matrix.md index 734bef4b..dc361844 100644 --- a/docs/matrix.md +++ b/docs/matrix.md @@ -56,12 +56,10 @@ longer answers. ### Upgrading a homeserver that already has ids -`serverName`'s default has changed across releases (from -`matrix.${services.hyperhive.domain}`, to the bare hive domain, to the -current swarm domain). A homeserver that has already minted ids under -an older default must **pin the value it actually minted them -under**, not adopt the new default — see above for why adopting a new -one strands existing users and rooms: +`serverName`'s default has changed across releases. A homeserver that +has already minted ids under an older default must **pin the value it +actually minted them under**, not adopt the new default — see above +for why adopting a new one strands existing users and rooms: ```nix services.hyperhive.swarm.matrix = { @@ -86,10 +84,6 @@ matters for access from *outside* the host. Flip to `true` when announcing the homeserver to other hives or when an external matrix client needs to reach the client-server API directly. -**Upgrading:** earlier releases defaulted `openFirewall` to `true`. -Operators relying on external reach need to add -`services.hyperhive.swarm.matrix.openFirewall = true;` explicitly now. - Federation port 8448 is intentionally not opened here — tuwunel serves the federation API on the same `httpPort` as client-server by default. Reaching it on 8448 needs either an explicit tuwunel