module system: revert "remove types.optionSet", just deprecate (#56857)

The explicit remove helped to uncover some hidden uses of `optionSet`
in NixOps. However it makes life harder for end-users of NixOps - it will
be impossible to deploy 19.03 systems with old NixOps, but there is no
new release of NixOps with `optionSet` fixes.

Also, "deprecation" process isn't well defined. Even that `optionSet` was
declared "deprecated" for many years, it was never announced. Hence, I
leave "deprecation" announce. Then, 3 releases after announce,
we can announce removal of this feature.

This type has to be removed, not `throw`-ed in runtime, because it makes
some perfectly fine code to fail. For example:
```
$ nix-instantiate --eval -E '(import <nixpkgs/lib>).types' --strict
trace: `types.list` is deprecated; use `types.listOf` instead
error: types.optionSet is deprecated; use types.submodule instead
(use '--show-trace' to show detailed location information)
```

4 files changed, 24 insertions, 6 deletions

diff --git a/lib/modules.nix b/lib/modules.nix
index a41c9da610ac..0869eae1982b 100644
--- a/lib/modules.nix
+++ b/lib/modules.nix
@@ -476,8 +476,22 @@ rec {
      optionSet to options of type submodule.  FIXME: remove
      eventually. */
   fixupOptionType = loc: opt:
-    if opt.type.getSubModules or null == null
-      then opt // { type = opt.type or types.unspecified; }
+    let
+      options = opt.options or
+        (throw "Option `${showOption loc'}' has type optionSet but has no option attribute, in ${showFiles opt.declarations}.");
+      f = tp:
+        let optionSetIn = type: (tp.name == type) && (tp.functor.wrapped.name == "optionSet");
+        in
+        if tp.name == "option set" || tp.name == "submodule" then
+          throw "The option ${showOption loc} uses submodules without a wrapping type, in ${showFiles opt.declarations}."
+        else if optionSetIn "attrsOf" then types.attrsOf (types.submodule options)
+        else if optionSetIn "loaOf"   then types.loaOf   (types.submodule options)
+        else if optionSetIn "listOf"  then types.listOf  (types.submodule options)
+        else if optionSetIn "nullOr"  then types.nullOr  (types.submodule options)
+        else tp;
+    in
+      if opt.type.getSubModules or null == null
+      then opt // { type = f (opt.type or types.unspecified); }
       else opt // { type = opt.type.substSubModules opt.options; options = []; };
 
 
diff --git a/lib/options.nix b/lib/options.nix
index d46dec6e41ca..a16a980398d6 100644
--- a/lib/options.nix
+++ b/lib/options.nix
@@ -48,6 +48,8 @@ rec {
     visible ? null,
     # Whether the option can be set only once
     readOnly ? null,
+    # Deprecated, used by types.optionSet.
+    options ? null
     } @ attrs:
     attrs // { _type = "option"; };
 
diff --git a/lib/types.nix b/lib/types.nix
index 7a88e1b9e36b..b225119299da 100644
--- a/lib/types.nix
+++ b/lib/types.nix
@@ -469,8 +469,10 @@ rec {
     # Obsolete alternative to configOf.  It takes its option
     # declarations from the ‘options’ attribute of containing option
     # declaration.
-    optionSet = builtins.throw "types.optionSet is deprecated; use types.submodule instead" "optionSet";
-
+    optionSet = mkOptionType {
+      name = builtins.trace "types.optionSet is deprecated; use types.submodule instead" "optionSet";
+      description = "option set";
+    };
     # Augment the given type with an additional type check function.
     addCheck = elemType: check: elemType // { check = x: elemType.check x && check x; };
 
diff --git a/nixos/doc/manual/release-notes/rl-1903.xml b/nixos/doc/manual/release-notes/rl-1903.xml
index e58ce49c79bd..a82724d7fb57 100644
--- a/nixos/doc/manual/release-notes/rl-1903.xml
+++ b/nixos/doc/manual/release-notes/rl-1903.xml
@@ -456,8 +456,8 @@
   </listitem>
   <listitem>
    <para>
-    Support for NixOS module system type <literal>types.optionSet</literal> and
-    <literal>lib.mkOption</literal> argument <literal>options</literal> is removed.
+    NixOS module system type <literal>types.optionSet</literal> and
+    <literal>lib.mkOption</literal> argument <literal>options</literal> are deprecated.
     Use <literal>types.submodule</literal> instead.
     (<link xlink:href="https://github.com/NixOS/nixpkgs/pull/54637">#54637</link>)
    </para>