diff --git a/doc/contributing/reviewing-contributions.chapter.md b/doc/contributing/reviewing-contributions.chapter.md index 0a90781d0c59..7a13a3f3b402 100644 --- a/doc/contributing/reviewing-contributions.chapter.md +++ b/doc/contributing/reviewing-contributions.chapter.md @@ -125,7 +125,7 @@ Reviewing process: - Type should be appropriate (string related types differs in their merging capabilities, `optionSet` and `string` types are deprecated). - Description, default and example should be provided. - Ensure that option changes are backward compatible. - - `mkRenamedOptionModule` and `mkAliasOptionModule` functions provide way to make option changes backward compatible. + - `mkRenamedOptionModuleWith` provides a way to make option changes backward compatible. - Ensure that removed options are declared with `mkRemovedOptionModule` - Ensure that changes that are not backward compatible are mentioned in release notes. - Ensure that documentations affected by the change is updated. diff --git a/lib/default.nix b/lib/default.nix index f8ab51c65794..6f7930c53430 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 01ba914ca80e..9bb8bfbbdf14 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 c68bac902e91..afae4f87254f 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 diff --git a/nixos/doc/manual/from_md/release-notes/rl-2205.section.xml b/nixos/doc/manual/from_md/release-notes/rl-2205.section.xml index 348374026b48..9846d21775c7 100644 --- a/nixos/doc/manual/from_md/release-notes/rl-2205.section.xml +++ b/nixos/doc/manual/from_md/release-notes/rl-2205.section.xml @@ -62,6 +62,14 @@ notes for details. + + + Module authors can use + mkRenamedOptionModuleWith to automate the + deprecation cycle without annoying out-of-tree module authors + and their users. + +
@@ -1200,7 +1208,8 @@ Legacy options have been mapped to the corresponding options under under nix.settings - but may be deprecated in the future. + and will be deprecated when NixOS 21.11 reaches end of + life. diff --git a/nixos/doc/manual/release-notes/rl-2205.section.md b/nixos/doc/manual/release-notes/rl-2205.section.md index 37ff778dd9b3..f2f77afa5577 100644 --- a/nixos/doc/manual/release-notes/rl-2205.section.md +++ b/nixos/doc/manual/release-notes/rl-2205.section.md @@ -21,6 +21,8 @@ In addition to numerous new and upgraded packages, this release has the followin - [`kops`](https://kops.sigs.k8s.io) defaults to 1.22.4, which will enable [Instance Metadata Service Version 2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html) and require tokens on new clusters with Kubernetes 1.22. This will increase security by default, but may break some types of workloads. See the [release notes](https://kops.sigs.k8s.io/releases/1.22-notes/) for details. +- Module authors can use `mkRenamedOptionModuleWith` to automate the deprecation cycle without annoying out-of-tree module authors and their users. + ## New Services {#sec-release-22.05-new-services} - [aesmd](https://github.com/intel/linux-sgx#install-the-intelr-sgx-psw), the Intel SGX Architectural Enclave Service Manager. Available as [services.aesmd](#opt-services.aesmd.enable). @@ -448,7 +450,7 @@ In addition to numerous new and upgraded packages, this release has the followin Similarly [virtualisation.vmVariantWithBootloader](#opt-virtualisation.vmVariantWithBootLoader) was added. - The configuration portion of the `nix-daemon` module has been reworked and exposed as [nix.settings](options.html#opt-nix-settings): - * Legacy options have been mapped to the corresponding options under under [nix.settings](options.html#opt-nix.settings) but may be deprecated in the future. + * Legacy options have been mapped to the corresponding options under under [nix.settings](options.html#opt-nix.settings) and will be deprecated when NixOS 21.11 reaches end of life. * [nix.buildMachines.publicHostKey](options.html#opt-nix.buildMachines.publicHostKey) has been added. - The `writers.writePyPy2`/`writers.writePyPy3` and corresponding `writers.writePyPy2Bin`/`writers.writePyPy3Bin` convenience functions to create executable Python 2/3 scripts using the PyPy interpreter were added. diff --git a/nixos/modules/services/misc/nix-daemon.nix b/nixos/modules/services/misc/nix-daemon.nix index 2b21df91b82f..d56808c7564e 100644 --- a/nixos/modules/services/misc/nix-daemon.nix +++ b/nixos/modules/services/misc/nix-daemon.nix @@ -112,11 +112,11 @@ in { imports = [ - (mkRenamedOptionModule [ "nix" "useChroot" ] [ "nix" "useSandbox" ]) - (mkRenamedOptionModule [ "nix" "chrootDirs" ] [ "nix" "sandboxPaths" ]) - (mkRenamedOptionModule [ "nix" "daemonIONiceLevel" ] [ "nix" "daemonIOSchedPriority" ]) + (mkRenamedOptionModuleWith { sinceRelease = 2003; from = [ "nix" "useChroot" ]; to = [ "nix" "useSandbox" ]; }) + (mkRenamedOptionModuleWith { sinceRelease = 2003; from = [ "nix" "chrootDirs" ]; to = [ "nix" "sandboxPaths" ]; }) + (mkRenamedOptionModuleWith { sinceRelease = 2205; from = [ "nix" "daemonIONiceLevel" ]; to = [ "nix" "daemonIOSchedPriority" ]; }) (mkRemovedOptionModule [ "nix" "daemonNiceLevel" ] "Consider nix.daemonCPUSchedPolicy instead.") - ] ++ mapAttrsToList (oldConf: newConf: mkRenamedOptionModule [ "nix" oldConf ] [ "nix" "settings" newConf ]) legacyConfMappings; + ] ++ mapAttrsToList (oldConf: newConf: mkRenamedOptionModuleWith { sinceRelease = 2205; from = [ "nix" oldConf ]; to = [ "nix" "settings" newConf ]; }) legacyConfMappings; ###### interface