From 85790b0ccabb55f9ebb7e8da51058da386c78f61 Mon Sep 17 00:00:00 2001
From: atlas <atlas@hyperhive>
Date: Sat, 30 May 2026 19:30:11 +0200
Subject: [PATCH] nix: add breaking-change note to each openFirewall
 description (argus #653)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

argus picked option (a) on #653: put the upgrade note in each option's
`description` so it shows up in `nix flake show` + the rendered
options docs, right next to the option itself. cheapest option, no
eval-time noise (a `warnings` block would fire on every new
deployment that wants false — the normal case now).

Appended a `**Breaking change as of #651**` paragraph to each of the
three `openFirewall` descriptions, naming the exact option string the
operator needs to set to restore the old behaviour.

Gateway's note specifically calls out that external reach is the
common case (operator's primary entry point), so the upgrade hint
is most likely needed there.
---
 nix/modules/hive-forge.nix   | 5 +++++
 nix/modules/hive-gateway.nix | 6 ++++++
 nix/modules/hive-matrix.nix  | 5 +++++
 3 files changed, 16 insertions(+)

diff --git a/nix/modules/hive-forge.nix b/nix/modules/hive-forge.nix
index 8abb20f4..64ad4ee4 100644
--- a/nix/modules/hive-forge.nix
+++ b/nix/modules/hive-forge.nix
@@ -98,6 +98,11 @@ in
         the operator's browser / external git clients to hit the
         forge directly. (The container shares host netns, so this
         is the only firewall layer that matters.)
+
+        **Breaking change as of #651**: this used to default to
+        `true`. If you relied on the old default for external
+        reach, add `services.hyperhive.forge.openFirewall = true;`
+        to your host config before rebuilding.
       '';
     };
   };
diff --git a/nix/modules/hive-gateway.nix b/nix/modules/hive-gateway.nix
index a81e088d..f051fe0d 100644
--- a/nix/modules/hive-gateway.nix
+++ b/nix/modules/hive-gateway.nix
@@ -93,6 +93,12 @@ in
         nginx vhost. Leave off when running behind another reverse
         proxy (e.g. caddy / traefik on the host) that handles TLS
         termination + forwards to `port`.
+
+        **Breaking change as of #651**: this used to default to
+        `true`. If you relied on the old default for external reach
+        (the common case — the gateway is the operator's primary
+        entry point), add `services.hyperhive.gateway.openFirewall = true;`
+        to your host config before rebuilding.
       '';
     };
 
diff --git a/nix/modules/hive-matrix.nix b/nix/modules/hive-matrix.nix
index 4ad016de..5be59b66 100644
--- a/nix/modules/hive-matrix.nix
+++ b/nix/modules/hive-matrix.nix
@@ -109,6 +109,11 @@ in
         the homeserver to other hives or when an external matrix
         client needs to reach the client-server API directly.
 
+        **Breaking change as of #651**: this used to default to
+        `true`. If you relied on the old default for external reach,
+        add `services.hyperhive.matrix.openFirewall = true;` to
+        your host config before rebuilding.
+
         Note: federation (the matrix-spec well-known port 8448) is
         intentionally not opened here. tuwunel serves the federation
         API on the same `httpPort` as the client-server API by