doc: document when newer builtins become usable

Based on https://discourse.nixos.org/t/when-is-a-nix-builtin-function-builtins-considered-ready-to-be-used-inside-nixpkgs/35369

Author: GraysonTinker

doc/functions.md

@@ -4,6 +4,7 @@ The Nixpkgs repository has several utility functions to manipulate Nix expressio
 
 ```{=include=} sections
 functions/library.md
+functions/newer-builtins.section.md
 functions/generators.section.md
 functions/debug.section.md
 functions/prefer-remote-fetch.section.md

doc/functions/newer-builtins.section.md

@@ -0,0 +1,36 @@
+# Using Newer Builtins {#sec-newer-builtins}
+
+Newer versions of Nix sometimes create new builtin functions, which can add new functionality or be more efficient versions of existing functions in `lib`.
+However, these new builtins can only be used in limited ways for a significant period of time after they were added.
+This is because of Nixpkgs' compatibility promise with older versions of Nix.
+
+The oldest version of Nix that Nixpkgs supports is listed in `lib/minfeatures.nix`.
+Any evaluation of Nixpkgs with an older Nix will fail.
+There is no specific process for raising the minimum version.
+
+The usage of functions added in newer Nix versions has to be done with care.
+In general, packages must not use the newer builtin themselves.
+Instead, `lib` can utilize these functions to improve the efficiency of existing functions, while still providing a fallback implementation in Nix for older versions.
+
+```nix
+  # In lib
+  function = builtins.function or (/* implementation without new builtins */)
+```
+
+Even when a builtin may be used directly, try to use the applicable `lib` function instead when available.
+Using `lib` functions makes it much easier to evolve their functionality over time, because they are not bound to Nix's strict backwards compatibility policy.
+
+<!--## Builtins From Nix Forks {#sec-nix-fork-builtins}
+
+TODO: Fill in this section once the status of PRs like #498999 is determined.
+
+Some forks of Nix provide additional language builtins that are not present in upstream Nix.
+While useful for improving performance for the users of the fork, usage of these can be problematic because they bind Nixpkgs to the (possibly varied) implementations of the fork(s).
+These builtins...
+
+Depending on the outcome, some ideas:
+- may be used, provided their behavior matches the calling `lib` function exactly and a fallback implementation remains available indefinitely. They should never be called within packages.
+- must not be used, because we can't make guarantees about their behavior.
+- <omit the section entirely>
+
+-->

doc/redirects.json

@@ -472,6 +472,9 @@
   "chap-overlays": [
     "index.html#chap-overlays"
   ],
+  "sec-newer-builtins": [
+    "index.html#sec-newer-builtins"
+  ],
   "sec-nixpkgs-release-26.11": [
     "release-notes.html#sec-nixpkgs-release-26.11"
   ],