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 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 what about 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 = "Migration step required: Move files from this location to that location, then bump the `stateVersion` to `1`. Check https://nixos-mailserver.readthedocs.io/en/latest/migrations.html for more 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
referenc the correct anchor in the URL you put into the assertionn message.
