From 424b0cefa44c3b08e1f71ae48e3621a72931739a Mon Sep 17 00:00:00 2001 From: K900 Date: Fri, 27 Oct 2023 11:29:06 +0300 Subject: nixos/version: rewrite stateVersion documentation Match the comment in nixos-generate-config and add some more details for the curious. --- nixos/modules/misc/version.nix | 42 ++++++++++++++++++++++++++---------------- 1 file changed, 26 insertions(+), 16 deletions(-) (limited to 'nixos/modules/misc/version.nix') diff --git a/nixos/modules/misc/version.nix b/nixos/modules/misc/version.nix index 0a66eafe933..45dbf45b3ae 100644 --- a/nixos/modules/misc/version.nix +++ b/nixos/modules/misc/version.nix @@ -121,22 +121,32 @@ in default = cfg.release; defaultText = literalExpression "config.${opt.release}"; description = lib.mdDoc '' - Every once in a while, a new NixOS release may change - configuration defaults in a way incompatible with stateful - data. For instance, if the default version of PostgreSQL - changes, the new version will probably be unable to read your - existing databases. To prevent such breakage, you should set the - value of this option to the NixOS release with which you want - to be compatible. The effect is that NixOS will use - defaults corresponding to the specified release (such as using - an older version of PostgreSQL). - It’s perfectly fine and recommended to leave this value at the - release version of the first install of this system. - Changing this option will not upgrade your system. In fact it - is meant to stay constant exactly when you upgrade your system. - You should only bump this option, if you are sure that you can - or have migrated all state on your system which is affected - by this option. + This option defines the first version of NixOS you have installed on this particular machine, + and is used to maintain compatibility with application data (e.g. databases) created on older NixOS versions. + + For example, if NixOS version XX.YY ships with AwesomeDB version N by default, and is then + upgraded to version XX.YY+1, which ships AwesomeDB version N+1, the existing databases + may no longer be compatible, causing applications to fail, or even leading to data loss. + + The `stateVersion` mechanism avoids this situation by making the default version of such packages + conditional on the first version of NixOS you've installed (encoded in `stateVersion`), instead of + simply always using the latest one. + + Note that this generally only affects applications that can't upgrade their data automatically - + applications and services supporting automatic migrations will remain on latest versions when + you upgrade. + + Most users should **never** change this value after the initial install, for any reason, + even if you've upgraded your system to a new NixOS release. + + This value does **not** affect the Nixpkgs version your packages and OS are pulled from, + so changing it will **not** upgrade your system. + + This value being lower than the current NixOS release does **not** mean your system is + out of date, out of support, or vulnerable. + + Do **not** change this value unless you have manually inspected all the changes it would + make to your configuration, and migrated your data accordingly. ''; }; -- cgit 1.4.1