lib: add deprecated option warning helpers

modules/lib/deprecations.nix

@@ -1,5 +1,47 @@
 { lib }:
 {
+  /*
+    Builds a standard warning for an option value shape that is deprecated.
+
+    Example:
+      mkDeprecatedOptionValueWarning {
+        option = [ "programs" "example" "settings" ];
+        old = "a list";
+        replacement = "`programs.example.settings.items`";
+      }
+
+    => Using `programs.example.settings` as a list is deprecated and will be
+       removed in a future release. Please use `programs.example.settings.items`
+       instead.
+  */
+  mkDeprecatedOptionValueWarning =
+    {
+      option,
+      old,
+      replacement,
+      details ? "",
+    }:
+    ''
+      Using `${lib.showOption option}` as ${old} is deprecated and will be
+      removed in a future release. Please use ${replacement} instead.
+    ''
+    + lib.optionalString (details != "") ''
+
+      ${details}
+    '';
+
+  # Builds a standard warning for an option value that has been renamed.
+  mkDeprecatedOptionValueRenameWarning =
+    {
+      option,
+      old,
+      replacement,
+    }:
+    ''
+      The value ${old} for `${lib.showOption option}` is deprecated and will be
+      removed in a future release. Please use ${replacement} instead.
+    '';
+
   /*
     Returns a function that maps
       [

tests/default.nix

@@ -177,6 +177,7 @@ import nmtSrc {
       (
         [
           # keep-sorted start case=no numeric=yes
+          ./lib/deprecations
           ./lib/generators
           ./lib/types
           ./modules/files

tests/lib/deprecations/default.nix

@@ -0,0 +1,3 @@
+{
+  lib-deprecations-warnings = ./warnings.nix;
+}

tests/lib/deprecations/warnings.nix

@@ -0,0 +1,42 @@
+{ lib, pkgs, ... }:
+
+{
+  nmt.script =
+    let
+      expected = pkgs.writeText "deprecation-warnings.expected" ''
+        Using `programs.example.settings` as a list is deprecated and will be
+        removed in a future release. Please use `programs.example.settings.items` instead.
+
+        Move list entries under `settings.items`.
+
+        The value "kde6" for `qt.platformTheme.name` is deprecated and will be
+        removed in a future release. Please use "kde" instead.
+      '';
+
+      actual = pkgs.writeText "deprecation-warnings.actual" (
+        lib.hm.deprecations.mkDeprecatedOptionValueWarning {
+          option = [
+            "programs"
+            "example"
+            "settings"
+          ];
+          old = "a list";
+          replacement = "`programs.example.settings.items`";
+          details = "Move list entries under `settings.items`.";
+        }
+        + "\n"
+        + lib.hm.deprecations.mkDeprecatedOptionValueRenameWarning {
+          option = [
+            "qt"
+            "platformTheme"
+            "name"
+          ];
+          old = ''"kde6"'';
+          replacement = ''"kde"'';
+        }
+      );
+    in
+    ''
+      assertFileContent ${actual} ${expected}
+    '';
+}