From 37d08685e8d27542b32edb4a72433e66a41f65cd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=A9clairevoyant?=
 <848000+eclairevoyant@users.noreply.github.com>
Date: Wed, 5 Feb 2025 22:50:36 -0500
Subject: [PATCH] nixos/version: validate system.stateVersion

---
 .../manual/release-notes/rl-2505.section.md   |  2 ++
 nixos/modules/misc/version.nix                | 22 +++++++++++++++++++
 2 files changed, 24 insertions(+)

diff --git a/nixos/doc/manual/release-notes/rl-2505.section.md b/nixos/doc/manual/release-notes/rl-2505.section.md
index 3c166bab99be..6d8cc3723bce 100644
--- a/nixos/doc/manual/release-notes/rl-2505.section.md
+++ b/nixos/doc/manual/release-notes/rl-2505.section.md
@@ -437,6 +437,8 @@
   - Overriding Wayland compositor is possible using `enableWaylandSession` option, but you might need to take care [`xfce4-session`](https://gitlab.xfce.org/xfce/xfce4-session/-/merge_requests/49), [`dbus-update-activation-environment`](https://github.com/labwc/labwc/blob/eaf11face68ee1f1bcc7ce1498304ca8c108c8ba/src/config/session.c#L234) and [`systemctl --user import-environment`](https://github.com/labwc/labwc/blob/eaf11face68ee1f1bcc7ce1498304ca8c108c8ba/src/config/session.c#L239) on startup.
   - For new Xfce installations, default panel layout has [changed](https://gitlab.xfce.org/xfce/xfce4-panel/-/merge_requests/158/diffs) to not include external panel plugins by default. You can still add them yourself using the "Panel Preferences" dialog.
 
+- [`system.stateVersion`](#opt-system.stateVersion) is now validated and must be in the `"YY.MM"` format, ideally corresponding to a prior NixOS release.
+
 - GOverlay has been updated to 1.2, please check the [upstream changelog](https://github.com/benjamimgois/goverlay/releases) for more details.
 
 - [`services.mongodb`](#opt-services.mongodb.enable) is now compatible with the `mongodb-ce` binary package. To make use of it, set [`services.mongodb.package`](#opt-services.mongodb.package) to `pkgs.mongodb-ce`.
diff --git a/nixos/modules/misc/version.nix b/nixos/modules/misc/version.nix
index b1a58be8ef4c..5610afc8168d 100644
--- a/nixos/modules/misc/version.nix
+++ b/nixos/modules/misc/version.nix
@@ -16,6 +16,7 @@ let
     toLower
     optionalString
     literalExpression
+    match
     mkRenamedOptionModule
     mkDefault
     mkOption
@@ -263,6 +264,27 @@ in
 
   config = {
 
+    assertions = [
+      {
+        assertion = match "[0-9]{2}\\.[0-9]{2}" config.system.stateVersion != null;
+        message = ''
+          ${config.system.stateVersion} is an invalid value for 'system.stateVersion'; it must be in the format "YY.MM",
+          which corresponds to a prior release of NixOS.
+
+          If you want to switch releases or switch to unstable, you should change your channel and/or flake input URLs only.
+          *DO NOT* touch the 'system.stateVersion' option, as it will not help you upgrade.
+          Leave it exactly on the previous value, which is likely the value you had for it when you installed your system.
+
+          If you're unsure which value to set it to, use "${
+            if match "[0-9]{2}\\.[0-9]{2}" options.system.stateVersion.default != null then
+              options.system.stateVersion.default
+            else
+              options.system.nixos.release.default
+          }" as a default.
+        '';
+      }
+    ];
+
     system.nixos = {
       # These defaults are set here rather than up there so that
       # changing them would not rebuild the manual