lib: Add mkRenamedOptionModuleWith

Adds support for sinceRelease

1 files changed, 28 insertions, 0 deletions

diff --git a/lib/modules.nix b/lib/modules.nix
index 79d54e4a538..0c9c88d2b61 100644
--- a/lib/modules.nix
+++ b/lib/modules.nix
@@ -904,6 +904,34 @@ rec {
     use = builtins.trace "Obsolete option `${showOption from}' is used. It was renamed to `${showOption to}'.";
   };
 
+  mkRenamedOptionModuleWith = {
+    /* Old option path as list of strings. */
+    from,
+    /* New option path as list of strings. */
+    to,
+
+    /*
+      Release number of the first release that contains the rename, ignoring backports.
+      Set it to the upcoming release, matching the nixpkgs/.version file.
+    */
+    sinceRelease,
+
+    /*
+      Options intended for reading by user modules/configuration should set this
+      to false.
+
+      Usually the user modules don't read the option and we want to hold nixpkgs
+      itself to a high standard immediately.
+      */
+    warnWhenRead ? true
+  }: doRename {
+    inherit from to;
+    visible = false;
+    warn = lib.isInOldestRelease sinceRelease;
+    use = lib.warnIf (warnWhenRead || lib.isInOldestRelease sinceRelease)
+      "Obsolete option `${showOption from}' is used. It was renamed to `${showOption to}'.";
+  };
+
   /* Return a module that causes a warning to be shown if any of the "from"
      option is defined; the defined values can be used in the "mergeFn" to set
      the "to" value.