From 7377ea57ff104ba49b2b0b2b838a8c7bfbc55cea Mon Sep 17 00:00:00 2001 From: Robert Hensing Date: Wed, 9 Mar 2022 14:41:43 +0100 Subject: [PATCH 1/6] lib: Add mkRenamedOptionModuleWith Adds support for sinceRelease --- lib/default.nix | 5 +++-- lib/modules.nix | 28 ++++++++++++++++++++++++++++ lib/trivial.nix | 24 ++++++++++++++++++++++++ 3 files changed, 55 insertions(+), 2 deletions(-) diff --git a/lib/default.nix b/lib/default.nix index 3fead03a463..916399cee17 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 @@ -119,7 +119,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 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. diff --git a/lib/trivial.nix b/lib/trivial.nix index c68bac902e9..afae4f87254 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 From 646e88801113aaa9e2d255853d7de04066440b36 Mon Sep 17 00:00:00 2001 From: Robert Hensing Date: Wed, 9 Mar 2022 14:43:13 +0100 Subject: [PATCH 2/6] nixos/nix-daemon: Stop warning about nix.settings Out-of-tree modules that use it can not upgrade yet. There's no real hurry and we should avoid warning fatigue. --- nixos/doc/manual/release-notes/rl-2205.section.md | 2 +- nixos/modules/services/misc/nix-daemon.nix | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/nixos/doc/manual/release-notes/rl-2205.section.md b/nixos/doc/manual/release-notes/rl-2205.section.md index b9402ba5f9d..54910ca201a 100644 --- a/nixos/doc/manual/release-notes/rl-2205.section.md +++ b/nixos/doc/manual/release-notes/rl-2205.section.md @@ -386,7 +386,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 2b21df91b82..d56808c7564 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 From 3e39e243db681acf8c0aeeeb8d6a9b27b0f02240 Mon Sep 17 00:00:00 2001 From: Robert Hensing Date: Wed, 9 Mar 2022 14:48:47 +0100 Subject: [PATCH 3/6] doc/reviewing-contributions: Recommend mkRenamedOptionModuleWith --- doc/contributing/reviewing-contributions.chapter.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/contributing/reviewing-contributions.chapter.md b/doc/contributing/reviewing-contributions.chapter.md index 0a90781d0c5..7a13a3f3b40 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. From 11d74c38718574b3cdb46999ce6399b0acbd560e Mon Sep 17 00:00:00 2001 From: Robert Hensing Date: Wed, 9 Mar 2022 14:57:55 +0100 Subject: [PATCH 4/6] nixos/rl-2205: Add mkRenamedOptionModuleWith --- nixos/doc/manual/release-notes/rl-2205.section.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/nixos/doc/manual/release-notes/rl-2205.section.md b/nixos/doc/manual/release-notes/rl-2205.section.md index 54910ca201a..56b30d1dc35 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). From ca8fa3bb6e2c924ffcf18843268df37c7871308d Mon Sep 17 00:00:00 2001 From: Robert Hensing Date: Wed, 9 Mar 2022 15:07:48 +0100 Subject: [PATCH 5/6] rl-2205.section.xml: Regenerate --- .../manual/from_md/release-notes/rl-2205.section.xml | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) 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 0c10451add4..44eb00f3ffd 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. + +
@@ -1050,7 +1058,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. From 1eb627c4cf62f50b647d2bf287d1ea97e326539f Mon Sep 17 00:00:00 2001 From: Robert Hensing Date: Mon, 21 Mar 2022 14:39:19 +0100 Subject: [PATCH 6/6] lib.mkRenamedOptionModuleWith: Remove warnWhenRead Let's keep things simple and not poke holes in the improved migration process. --- lib/modules.nix | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/lib/modules.nix b/lib/modules.nix index 0c9c88d2b61..093a901ff3d 100644 --- a/lib/modules.nix +++ b/lib/modules.nix @@ -916,19 +916,11 @@ rec { */ 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) + use = lib.warnIf (lib.isInOldestRelease sinceRelease) "Obsolete option `${showOption from}' is used. It was renamed to `${showOption to}'."; };