diff options
author | Alyssa Ross <hi@alyssa.is> | 2023-11-21 16:12:21 +0100 |
---|---|---|
committer | Alyssa Ross <hi@alyssa.is> | 2023-11-21 16:12:48 +0100 |
commit | 048a4cd441a59cbf89defb18bb45c9f0b4429b35 (patch) | |
tree | f8f5850ff05521ab82d65745894714a8796cbfb6 /nixos/modules/misc/version.nix | |
parent | 030c5028b07afcedce7c5956015c629486cc79d9 (diff) | |
parent | 4c2d05dd6435d449a3651a6dd314d9411b5f8146 (diff) | |
download | nixpkgs-rootfs.tar nixpkgs-rootfs.tar.gz nixpkgs-rootfs.tar.bz2 nixpkgs-rootfs.tar.lz nixpkgs-rootfs.tar.xz nixpkgs-rootfs.tar.zst nixpkgs-rootfs.zip |
Signed-off-by: Alyssa Ross <hi@alyssa.is>
Diffstat (limited to 'nixos/modules/misc/version.nix')
-rw-r--r-- | nixos/modules/misc/version.nix | 42 |
1 files changed, 26 insertions, 16 deletions
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. ''; }; |