Merge master into haskell-updates

3 files changed, 47 insertions, 2 deletions

diff --git a/lib/default.nix b/lib/default.nix
index f8ab51c657948..6f7930c53430d 100644
--- a/lib/default.nix
+++ b/lib/default.nix
@@ -67,7 +67,7 @@ let
     inherit (self.trivial) id const pipe concat or and bitAnd bitOr bitXor
       bitNot boolToString mergeAttrs flip mapNullable inNixShell isFloat min max
       importJSON importTOML warn warnIf throwIfNot checkListOfEnum
-      info showWarnings nixpkgsVersion version
+      info showWarnings nixpkgsVersion version isInOldestRelease
       mod compare splitByAndCompare functionArgs setFunctionArgs isFunction
       toHexString toBaseDigits;
     inherit (self.fixedPoints) fix fix' converge extends composeExtensions
@@ -120,7 +120,8 @@ let
       mkOptionDefault mkDefault mkImageMediaOverride mkForce mkVMOverride
       mkFixStrictness mkOrder mkBefore mkAfter mkAliasDefinitions
       mkAliasAndWrapDefinitions fixMergeModules mkRemovedOptionModule
-      mkRenamedOptionModule mkMergedOptionModule mkChangedOptionModule
+      mkRenamedOptionModule mkRenamedOptionModuleWith
+      mkMergedOptionModule mkChangedOptionModule
       mkAliasOptionModule mkDerivedConfig doRename;
     inherit (self.options) isOption mkEnableOption mkSinkUndeclaredOptions
       mergeDefaultOption mergeOneOption mergeEqualOption mergeUniqueOption
diff --git a/lib/modules.nix b/lib/modules.nix
index 01ba914ca80ef..9bb8bfbbdf144 100644
--- a/lib/modules.nix
+++ b/lib/modules.nix
@@ -954,6 +954,26 @@ 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,
+
+  }: doRename {
+    inherit from to;
+    visible = false;
+    warn = lib.isInOldestRelease sinceRelease;
+    use = lib.warnIf (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.
diff --git a/lib/trivial.nix b/lib/trivial.nix
index c68bac902e913..afae4f87254f5 100644
--- a/lib/trivial.nix
+++ b/lib/trivial.nix
@@ -166,6 +166,30 @@ rec {
   /* Returns the current nixpkgs release number as string. */
   release = lib.strings.fileContents ../.version;
 
+  /* The latest release that is supported, at the time of release branch-off,
+     if applicable.
+
+     Ideally, out-of-tree modules should be able to evaluate cleanly with all
+     supported Nixpkgs versions (master, release and old release until EOL).
+     So if possible, deprecation warnings should take effect only when all
+     out-of-tree expressions/libs/modules can upgrade to the new way without
+     losing support for supported Nixpkgs versions.
+
+     This release number allows deprecation warnings to be implemented such that
+     they take effect as soon as the oldest release reaches end of life. */
+  oldestSupportedRelease =
+    # Update on master only. Do not backport.
+    2111;
+
+  /* Whether a feature is supported in all supported releases (at the time of
+     release branch-off, if applicable). See `oldestSupportedRelease`. */
+  isInOldestRelease =
+    /* Release number of feature introduction as an integer, e.g. 2111 for 21.11.
+       Set it to the upcoming release, matching the nixpkgs/.version file.
+    */
+    release:
+      release <= lib.trivial.oldestSupportedRelease;
+
   /* Returns the current nixpkgs release code name.
 
      On each release the first letter is bumped and a new animal is chosen