docs: migration notes for telegram notification

crazy-max · crazy-max · commit 150d9868a1c8 · 2024-12-20T18:26:19.000+01:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,8 @@
 
 ## 4.29.0 (2024/12/19)
 
+:warning: See **Migration notes** in the documentation before upgrading.
+
 * Topics support for Telegram notifications (#1308)
 * Webhook url as secret support for Discord, Slack and Teams notifications (#1302)
 * Enhance error message for JSON decode response issues for Gotify, ntfy and RocketChat (#1309)
diff --git a/docs/migration/v4.1-to-v4.29.md b/docs/migration/v4.1-to-v4.29.md
@@ -0,0 +1,41 @@
+# Diun v4.28 to v4.29
+
+## Telegram `chatdIDs` and `chatIDsFile` attributes change
+
+The `chatIDs` attribute has changed from a list of integers to a list of
+strings. If you are using Telegram notifications, you need to update your
+configuration file:
+
+!!! example "v4.1"
+    ```yaml
+    notif:
+      telegram:
+        token: aabbccdd:11223344
+        chatIDs:
+          - 123456789
+          - 987654321
+    ```
+
+!!! example "v4.29"
+    ```yaml
+    notif:
+      telegram:
+        token: aabbccdd:11223344
+        chatIDs:
+          - "123456789"
+          - "987654321"
+    ```
+
+The same applies for the `chatIDsFile` attribute content:
+
+!!! example "v4.1"
+    ```json
+    [123456789,987654321]
+    ```
+
+!!! example "v4.29"
+    ```json
+    ["123456789","987654321"]
+    ```
+
+More information on [Telegram notifications](../notif/telegram.md#configuration) page.
diff --git a/docs/notif/telegram.md b/docs/notif/telegram.md
@@ -39,7 +39,7 @@ Multiple chat IDs can be provided in order to deliver notifications to multiple
     * `DIUN_NOTIF_TELEGRAM_TEMPLATEBODY`
 
 !!! example "chat IDs secret file"
-    Chat IDs secret file must be a valid JSON array like: `[123456789,987654321,"567891234:25","891256734:25;12"]`
+    Chat IDs secret file must be a valid JSON array like: `["123456789","987654321","567891234:25","891256734:25;12"]`
 
 ### `chatIDs` format
 
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -145,6 +145,7 @@ nav:
   - FAQ: faq.md
   - Changelog: changelog.md
   - Migration:
+    - Diun v4.1 to v4.29: migration/v4.1-to-v4.29.md
     - Diun v4.0 to v4.17: migration/v4.0-to-v4.17.md
     - Diun v3 to v4: migration/v3-to-v4.md
     - Diun v2 to v3: migration/v2-to-v3.md
