use-case: deeply replace packages

use-cases/deep-replace.org

@@ -0,0 +1,44 @@
+#+TITLE: Deeply Replacing Packages in Nixpkgs
+
+* General Information
+
+Replace all "instances" of a package across a dependency graph.
+This may be replacing all usage in a package set, collection of package sets,
+a collection of ad-hoc recipes, or a collection of flakes.
+
+A possible motivation for _deep replacement_ may be to ensure that a security
+fix provided by a new release of a piece of software is used "everywhere" in
+the dependency graph.
+
+
+* Concrete Examples
+
+While the precise organization of packages will effect the complexity and
+effort required to perform _deep replacement_, in general we say that this
+is accomplished using helper functions such as =callPackageWith=,
+=makeScope=, =override=, or =extend=.
+
+#+BEGIN_SRC nix
+let
+  nixpkgs  = builtins.getFlake "nixpkgs";
+  pkgsFor  = builtins.getAttr builtins.currentSystem nixpkgs.legacyPackages;
+  patchFoo = final: prev: { foo = final.callPackage ./my-pkgs/foo {}; };
+in ( pkgsFor.extend patchFoo ).bar
+#+END_SRC
+
+* Current Problems
+
+With this approach we have three main sources of complexity, none of which
+truly prevent a user from accomplishing their goal; but we might suffice to
+say that it may be worthwhile to provide a more straightforward mechanism
+for handling this use case.
+
+1. [[https://github.com/NixOS/nixpkgs/blob/master/lib/customization.nix][github:NixOS/nixpkgs://lib/customization.nix]] routines aren't intuitively understood by many users.
+
+2. Nested scopes are difficult to locate, and the relationship between
+   parent scopes and child scopes is not opaque to users.
+
+3. With ad-hoc recipes and flakes there isn't standardized usage of
+   =overlays= that allow deep overriding of packages transitively.
+   - Improved guidance on the use of =overlays= and =follows= in =flakes=
+     could help a bit here.