home-environment: require home.uid for stateVersion >= 26.05

Make home.uid mandatory for users with stateVersion 26.05 or later.
This follows up on the addition of home.uid in a521eab, addressing
the discussion about making the option required.

When using Home Manager as a NixOS or nix-darwin module, home.uid is
automatically set from users.users.<name>.uid when that option is
defined. For standalone usage or when the system user has no explicit
UID, users must now set home.uid directly.

Author: lovesegfault

docs/release-notes/rl-2605.md

@@ -15,3 +15,9 @@ changes are only active if the `home.stateVersion` option is set to
 
 - The `gtk.gtk4.theme` option does not mirror `gtk.theme` by default
   anymore.
+
+- The `home.uid` option is now required. When using Home Manager as a
+  NixOS or nix-darwin module, this is automatically set from
+  `users.users.<name>.uid` if that option is defined. For standalone
+  usage or when the system user has no explicit UID, set `home.uid`
+  to your user's UID (run `id -u` to find it).

modules/home-environment.nix

@@ -197,7 +197,13 @@ in
       type = types.nullOr types.ints.unsigned;
       default = null;
       example = 1000;
-      description = "The user's uid.";
+      description = ''
+        The user's UID. Required for state version 26.05 and later.
+
+        When using Home Manager as a NixOS or nix-darwin module, this value
+        is automatically set from {option}`users.users.<name>.uid` when that
+        option is defined.
+      '';
     };
 
     home.homeDirectory = mkOption {
@@ -572,6 +578,16 @@ in
         assertion = config.home.homeDirectory != "";
         message = "Home directory could not be determined";
       }
+      {
+        assertion = lib.versionOlder config.home.stateVersion "26.05" || config.home.uid != null;
+        message = ''
+          User ID (UID) could not be determined. Please set 'home.uid' to your
+          user's UID. You can find your UID by running 'id -u' in your terminal.
+
+          If you are using Home Manager as a NixOS or nix-darwin module, you can
+          alternatively set 'users.users.<name>.uid' in your system configuration.
+        '';
+      }
     ];
 
     warnings =

modules/misc/news/2025/12/2025-12-04_18-39-36.nix

@@ -0,0 +1,17 @@
+{ config, lib, ... }:
+
+{
+  time = "2025-12-04T18:39:36+00:00";
+  condition = lib.versionAtLeast config.home.stateVersion "26.05";
+  message = ''
+    The 'home.uid' option is now required for state version 26.05 and later.
+
+    When using Home Manager as a NixOS or nix-darwin module, this value is
+    automatically set from 'users.users.<name>.uid' when that option is defined.
+
+    For standalone usage, or when the system user has no explicit UID, add to
+    your configuration:
+
+        home.uid = 1000;  # Replace with your actual UID (run 'id -u')
+  '';
+}

tests/modules/home-environment/default.nix

@@ -5,4 +5,5 @@
   home-nixpkgs-release-check-pkgs = ./nixpkgs-release-check-pkgs.nix;
   home-uid = ./uid.nix;
   home-uid-null = ./uid-null.nix;
+  home-uid-required = ./uid-required.nix;
 }

tests/modules/home-environment/uid-required.nix

@@ -0,0 +1,14 @@
+{
+  home.stateVersion = "26.05";
+  # home.uid defaults to null, which should trigger assertion for 26.05+
+
+  test.asserts.assertions.expected = [
+    ''
+      User ID (UID) could not be determined. Please set 'home.uid' to your
+      user's UID. You can find your UID by running 'id -u' in your terminal.
+
+      If you are using Home Manager as a NixOS or nix-darwin module, you can
+      alternatively set 'users.users.<name>.uid' in your system configuration.
+    ''
+  ];
+}