lib: Discourage use of extend (#376033)

doc/module-system/module-system.chapter.md

@@ -31,6 +31,15 @@ An attribute set of module arguments that can be used in `imports`.
 
 This is in contrast to `config._module.args`, which is only available after all `imports` have been resolved.
 
+::: {.warning}
+You may be tempted to use `specialArgs.lib` to provide extra library functions. Doing so limits the interoperability of modules, as well as the interoperability of Module System applications.
+
+`lib` is reserved for the Nixpkgs library, and should not be used for custom functions.
+
+Instead, you may create a new attribute in `specialArgs` to provide custom functions.
+This clarifies their origin and avoids incompatibilities.
+:::
+
 #### `class` {#module-system-lib-evalModules-param-class}
 
 If the `class` attribute is set and non-`null`, the module system will reject `imports` with a different `_class` declaration.

flake.nix

@@ -24,6 +24,8 @@
 
         - `lib.nixos` for other NixOS-provided functionality, such as [`runTest`](https://nixos.org/manual/nixos/unstable/#sec-call-nixos-test-outside-nixos)
       */
+      # DON'T USE lib.extend TO ADD NEW FUNCTIONALITY.
+      # THIS WAS A MISTAKE. See the warning in lib/default.nix.
       lib = lib.extend (final: prev: {
 
         /**

lib/default.nix

@@ -5,9 +5,41 @@
  */
 let
 
-  inherit (import ./fixed-points.nix { inherit lib; }) makeExtensible;
+  # A copy of `lib.makeExtensible'` in order to document `extend`.
+  # It has been leading to some trouble, so we have to document it specially.
+  makeExtensible' =
+    rattrs:
+    let self = rattrs self // {
+          /**
+            Patch the Nixpkgs library
 
-  lib = makeExtensible (self: let
+            A function that applies patches onto the nixpkgs library.
+            Usage is discouraged for most scenarios.
+
+            :::{.note}
+            The name `extends` is a bit misleading, as it doesn't actually extend the library, but rather patches it.
+            It is merely a consequence of being implemented by `makeExtensible`.
+            :::
+
+            # Inputs
+
+            - An "extension function" `f` that returns attributes that will be updated in the returned Nixpkgs library.
+
+            # Output
+
+            A patched Nixpkgs library.
+
+            :::{.warning}
+            This functionality is intended as an escape hatch for when the provided version of the Nixpkgs library has a flaw.
+
+            If you were to use it to add new functionality, you will run into compatibility and interoperability issues.
+            :::
+          */
+          extend = f: lib.makeExtensible (lib.extends f rattrs);
+        };
+    in self;
+
+  lib = makeExtensible' (self: let
     callLibs = file: import file { lib = self; };
   in {