Merge branch 'stateVersion' into 'master'

Introduce stateVersion concept

See merge request simple-nixos-mailserver/nixos-mailserver!401

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" ];