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
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^