Introduce stateVersion concept

With upcoming changes to the dovecot home and maildirectories we need to
introduce a way to nudge users to inform themselves about manual
migration steps they might need to carry out.

The idea here is to allow us to safely make breaking changes and notify
the user of required migration steps at eval time, so they can make the
necessary changes in time.

docs/howto-develop.rst

@@ -64,3 +64,44 @@ To build the documentation, you need to enable `Nix Flakes
 
    $ nix build .#documentation
    $ xdg-open result/index.html
+
+
+Manual migrations
+-----------------
+
+We need to take great care around providing a migration story around breaking
+changes. If manual intervention becomes necessary we provide the `stateVersion`
+option to notify the user that they need to complete a migration before
+they can deploy an update.
+
+If that is the case for your change, find the highest `stateVersion` that is
+being asserted on in `mail-server/assertions.nix`. Then pick the next number
+and add a new assertion, write a good summary describing the issue and what
+remediation steps are necessary. Finally reference the URL to the specific
+section on the migration page in the documentation.
+
+.. code-block:: nix
+
+  {
+    assertions = [
+      {
+        assertion = config.mailserver.stateVersion < 1;
+        message = ''
+          Problem: The home directory for the foobar service is snafu.
+          Remediation:
+            - Stop the `foobar.service`
+            - Rename `/var/lib/foobaz` to `/var/lib/foobar`
+            - Increase the `mailserver.stateVersion` to 1.
+
+          Check https://nixos-mailserver.readthedocs.io/en/latest/migrations.html#specific-anchor-here for further details.
+        '';
+      }
+    ];
+  }
+
+The setup guide should always reference the latest `stateVersion`, since we
+don't require any migration steps for new setups.
+
+The migration documentation should paint a more complete picture about the steps
+that need to be carried out and why this has become necessary. Make sure to
+reference the correct anchor in the URL you put into the assertion message.

docs/index.rst

@@ -18,6 +18,7 @@ Welcome to NixOS Mailserver's documentation!
    faq
    release-notes
    options
+   migrations
 
 .. toctree::
    :maxdepth: 1

docs/migrations.rst

@@ -0,0 +1,22 @@
+Migrations
+==========
+
+With mail server configuration best practices changing over time we might need
+to make changes that require you to complete manual migration steps before you
+can deploy a new version of NixOS mailserver.
+
+The initial `mailserver.stateVersion` value should be copied from the setup
+guide that you used to initially set up your mail server. If in doubt you can
+always initialize it at `1` and walk through all assertions, that might apply
+to your setup.
+
+NixOS 25.11
+-----------
+
+This option was introduced in the NixOS 25.11 release cycle, in which case you
+can safely initialize its value at `1`.
+
+:: code-block: nix
+
+   mailserver.stateVersion = 1;
+

docs/setup-guide.rst

@@ -72,6 +72,7 @@ common ones.
 
      mailserver = {
        enable = true;
+       stateVersion = 1;
        fqdn = "mail.example.com";
        domains = [ "example.com" ];