sieve: add migration story for cfg.sieveDirectory removal

Co-authored-by: Martin Weinelt <hexa@darmstadt.ccc.de>

docs/migrations.rst

@@ -13,6 +13,87 @@ apply to your setup.
 NixOS 26.05
 -----------
 
+#5 Sieve script directory migration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Sieve scripts managed by users via ManageSieve were previously stored in
+``/var/sieve`` (or via the now-removed option
+``mailserver.sieveDirectory``). This setup partially mirrored the mail
+directory structure in ``/var/vmail`` (``mailserver.storage.path``),
+which proved to be fragile and error-prone.
+
+Thanks to a `prior migration`_, we can now migrate these directories into each
+user’s home directory, aligning with upstream recommendations — almost
+nine years later.
+
+.. _prior migration: #dovecot-mail-directory-migration
+
+This migration is only required if you have :option:`mailserver.enableManageSieve` enabled.
+
+1. If you are coming from ``25.11`` and are using LDAP, temporarily disable
+   :option:`mailserver.enableManageSieve` by setting it to ``false``, deploy,
+   and only then continue with this migration.
+
+   If you are not coming from ``25.11`` or are not using LDAP, continue with
+   this migration as is.
+
+2. Copy the migration script to your mailserver and make it executable:
+
+   .. code-block:: console
+
+      cd /tmp
+      wcurl https://gitlab.com/simple-nixos-mailserver/nixos-mailserver/-/raw/main/migrations/nixos-mailserver-migration-05.py
+      chmod +x nixos-mailserver-migration-05.py
+
+3. Stop the ``postfix.service``.
+
+   .. code-block:: bash
+
+      systemctl stop postfix.service
+
+4. Create a backup or snapshot of your ``mailserver.sieveDirectory``, so
+   you can restore should anything go wrong.
+
+5. Run the migration script and pass your ``mailserver.sieveDirectory`` as argument:
+
+   The script should be run under the user who owns the ``mailserver.sieveDirectory``.
+   If run as root it will automatically switch into the appropriate user by itself.
+
+   The script will not modify your data unless called with ``--execute``.
+
+   The migration script finds all Sieve script directories in
+   ``/var/sieve/`` (or any other ``mailserver.sieveDirectory``), for
+   example that of ``bob`` at ``/var/vmail/bob@example.com``.
+
+   It then takes ``bob@example.com`` and looks up the home directory
+   for ``bob``. Finally, it starts suggesting the necessary move
+   operations to migrate the Sieve directory to
+   ``/var/vmail/example.com/bob/sieve`` and symlinks the active script
+   to ``/var/vmail/example.com/bob/.dovecot.sieve``.
+
+   Example:
+
+   .. code-block:: bash
+
+      ./nixos-mailserver-migration-05.py \
+         /var/sieve
+
+6. Review the script output.
+
+   The script can highlight various inconsistencies and problems, that should
+   be reviewed and acted upon.
+
+   If in doubt, join our community chat for help before applying any changes.
+
+7. Rerun the command with ``--execute`` or run the proposed commands manually.
+
+8. Update the ``mailserver.stateVersion`` to ``5``.
+
+9. The previous Sieve directory (``mailserver.sieveDirectory``) should now be safe to delete.
+
+10. If you temporarily disabled :option:`mailserver.enableManageSieve` in step 1,
+    re-enable it now by setting it back to ``true``.
+
 #4 Dovecot LDAP UUID-based home directories
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

docs/release-notes.rst

@@ -49,6 +49,8 @@ NixOS 26.05
   - :option:`mailserver.borgbackup.enable`
   - :option:`mailserver.backup.enable`
   - :option:`mailserver.monitoring.enable`
+- Setups with :option:`mailserver.enableManageSieve` enabled require a
+  migration of the `Sieve script directories into Dovecot home directories`_.
 
 .. _setup guide: setup-guide.html#setup-the-server
 .. _DKIM key management: dkim.html
@@ -57,6 +59,7 @@ NixOS 26.05
 .. _AEAD: https://en.wikipedia.org/wiki/Authenticated_encryption
 .. _ECDHE: https://www.rfc-editor.org/rfc/rfc8422
 .. _UUID based home directories: migrations.html#dovecot-ldap-uuid-based-home-directories
+.. _Sieve script directories into Dovecot home directories: migrations.html#sieve-script-directory-migration
 
 NixOS 25.11
 -----------

docs/setup-example.nix

@@ -29,7 +29,7 @@
 
   mailserver = {
     enable = true;
-    stateVersion = 4;
+    stateVersion = 5;
     fqdn = "mail.example.com";
     domains = [ "example.com" ];