flake: remove superfluous arguments

Remove `stateVersion`, `username`, and `homeDirectory` as they can be
set in the configuration directly. Together with the previous commit,
this makes setting `stateVersion` explicitly mandatory.

Also replace `configuration` by `modules`, which expects a list of
Home Manager modules.

Also remove `system` which was made useless by #3028.

docs/nix-flakes.adoc

@@ -33,13 +33,6 @@ Unlike the channel-based setup,
 so it must be present before bootstrap of Home Manager from the flake.
 See <<sec-usage-configuration>> for introduction about
 writing a Home Manager configuration.
-+
-[NOTE]
-====
-The `stateVersion` will be specified in the flake instead of in the configuration file.
-
-Remove the line containing `home.stateVersion` in the example.
-====
 
 [[sec-flakes-standalone]]
 === Standalone setup
@@ -52,27 +45,27 @@ Remove the line containing `home.stateVersion` in the example.
   description = "Home Manager configuration of Jane Doe";
 
   inputs = {
-    # Specify the source of Home Manager and Nixpkgs
+    # Specify the source of Home Manager and Nixpkgs.
-    home-manager.url = "github:nix-community/home-manager";
     nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
-    home-manager.inputs.nixpkgs.follows = "nixpkgs";
+    home-manager = {
+      url = "github:nix-community/home-manager";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
   };
 
-  outputs = { home-manager, ... }:
+  outputs = { nixpkgs, home-manager, ... }:
     let
       system = "x86_64-linux";
-      username = "jdoe";
+      pkgs = nixpkgs.legacyPackages.${system};
     in {
-      homeConfigurations.${username} = home-manager.lib.homeManagerConfiguration {
+      homeConfigurations.jdoe = home-manager.lib.homeManagerConfiguration {
-        # Specify the path to your home configuration here
+        inherit pkgs;
-        configuration = import ./home.nix;
 
-        inherit system username;
+        # Specify your home configuration modules here, for example,
-        homeDirectory = "/home/${username}";
+        # the path to your home.nix.
-        # Update the state version as needed.
+        modules = [
-        # See the changelog here:
+          ./home.nix;
-        # https://nix-community.github.io/home-manager/release-notes.html#sec-release-21.05
+        ];
-        stateVersion = "22.05";
 
         # Optionally use extraSpecialArgs
         # to pass through arguments to home.nix
@@ -88,7 +81,6 @@ and nixos-unstable branch of Nixpkgs.
 If you would like to use the `release-22.05` branch,
 change the `home-manager` input url to `github:nix-community/home-manager/release-22.05`
 and `nixpkgs` url to `github:NixOS/nixpkgs/nixos-22.05`.
-Make sure to also update to the `stateVersion` option accordingly.
 
 * The Home Manager library is exported by the flake under
 `lib.hm`.

docs/release-notes/rl-2211.adoc

@@ -18,6 +18,63 @@ home.stateVersion = "18.09";
 +
 to your configuration.
 
+* The Flake function `homeManagerConfiguration` has been simplified.
+Specifically, the arguments
++
+--
+  - `configuration`,
+  - `username`,
+  - `homeDirectory`,
+  - `stateVersion`,
+  - `extraModules`, and
+  - `system`
+--
++
+have been removed. Instead use the new `modules` argument, which
+accepts a list of NixOS modules.
++
+Further, the `pkgs` argument is now mandatory and should be set to
+`nixpkgs.legacyPackages.${system}` where `nixpkgs` is the Nixpkgs
+input of your choice.
++
+For example, if your Flake currently contains
++
+[source,nix]
+----
+homeManagerConfiguration {
+  configuration = import ./home.nix;
+  system = "x86_64-linux";
+  username = "jdoe";
+  homeDirectory = "/home/jdoe";
+  stateVersion = "22.05";
+  extraModules = [ ./some-extra-module.nix ];
+}
+----
++
+then you can change it to
++
+[source,nix]
+----
+homeManagerConfiguration {
+  pkgs = nixpkgs.legacyPackages.${system};
+  modules = [
+    ./home.nix
+    ./some-extra-module.nix
+    {
+      home = {
+        username = "jdoe";
+        homeDirectory = "/home/jdoe";
+        stateVersion = "22.05";
+      };
+    }
+  ];
+}
+----
++
+Of course, you can move the assignment of <<opt-home.username>>,
+<<opt-home.homeDirectory>>, and <<opt-home.stateVersion>> to some
+other file or simply place them in your `home.nix`.
+
 [[sec-release-22.11-state-version-changes]]
 === State Version Changes
 

flake.nix

@@ -29,19 +29,40 @@
 
       lib = {
         hm = import ./modules/lib { lib = nixpkgs.lib; };
-        homeManagerConfiguration = { configuration, system, homeDirectory
+        homeManagerConfiguration = { modules ? [ ], pkgs, lib ? pkgs.lib
-          , username, extraModules ? [ ], extraSpecialArgs ? { }, pkgs
+          , extraSpecialArgs ? { }, check ? true
-          , lib ? pkgs.lib, check ? true, stateVersion ? "20.09" }@args:
+            # Deprecated:
-          assert nixpkgs.lib.versionAtLeast stateVersion "20.09";
+          , configuration ? null, extraModules ? null, stateVersion ? null
+          , username ? null, homeDirectory ? null, system ? null }@args:
+          let
+            throwForRemovedArg = v:
+              lib.throwIf (v != null) ''
+                The 'homeManagerConfiguration' arguments
 
-          import ./modules {
+                  - 'configuration',
+                  - 'username',
+                  - 'homeDirectory'
+                  - 'stateVersion',
+                  - 'extraModules', and
+                  - 'system'
+
+                have been removed. Instead use the arguments 'pkgs' and
+                'modules'. See the 22.11 release notes for more.
+              '';
+
+            throwForRemovedArgs = throwForRemovedArg configuration # \
+              throwForRemovedArg username # \
+              throwForRemovedArg homeDirectory # \
+              throwForRemovedArg stateVersion # \
+              throwForRemovedArg extraModules # \
+              throwForRemovedArg system;
+          in throwForRemovedArgs (import ./modules {
             inherit pkgs lib check extraSpecialArgs;
             configuration = { ... }: {
-              imports = [ configuration ] ++ extraModules;
+              imports = modules;
-              home = { inherit homeDirectory stateVersion username; };
               nixpkgs = { inherit (pkgs) config overlays; };
             };
-          };
+          });
       };
     } // utils.lib.eachDefaultSystem (system:
       let