lib: Document status of deprecated.nix and move it

This is all I could find after co-maintaining lib for a long time.
I've had the fortune of basically not really noticing this file,
because it has had very few interactions until the confusion in
https://github.com/NixOS/nixpkgs/pull/304277

It seems to be a state of limbo, which would be nice to resolve
(with great care), but this is not urgent, and first we should
document its status.

3 files changed, 12 insertions, 1 deletions

diff --git a/lib/default.nix b/lib/default.nix
index 486d412fbb6f..c74c930233d5 100644
--- a/lib/default.nix
+++ b/lib/default.nix
@@ -47,7 +47,7 @@ let
     # misc
     asserts = callLibs ./asserts.nix;
     debug = callLibs ./debug.nix;
-    misc = callLibs ./deprecated.nix;
+    misc = callLibs ./deprecated/misc.nix;
 
     # domain-specific
     fetchers = callLibs ./fetchers.nix;
diff --git a/lib/deprecated/README.md b/lib/deprecated/README.md
new file mode 100644
index 000000000000..afeb34d449f5
--- /dev/null
+++ b/lib/deprecated/README.md
@@ -0,0 +1,11 @@
+
+# lib/deprecated
+
+Do not add any new functions to this directory.
+
+This directory contains the `lib.misc` sublibrary, which - as a location - is deprecated.
+Furthermore, some of the functions inside are of *dubious* utility, and should perhaps be avoided,
+while some functions *may still be needed*.
+
+This directory does not play a role in the deprecation process for library functions.
+They should be deprecated in place, by putting a `lib.warn` or `lib.warnIf` call around the function.
diff --git a/lib/deprecated.nix b/lib/deprecated/misc.nix
index d556bccbec0b..d556bccbec0b 100644
--- a/lib/deprecated.nix
+++ b/lib/deprecated/misc.nix