From 4664ae4470091fe7b74040ad730f8039fd737216 Mon Sep 17 00:00:00 2001 From: Wolfgang Walther Date: Fri, 19 Sep 2025 21:07:06 +0200 Subject: [PATCH] pkgs/by-name/README: explicitly suggest version specific override interfaces The current advice of "keeping the override interface" is actively bad, because it hides certain expectations of a package function in an undiscoverable place. Ideally, all information about a package is in one, single place instead. Version-specific argument names, if required, also have the *benefit* of creating errors with downstream overrides, much like merge conflicts do. Instead of possibly silently breaking certain behavior, they make a change in expectations clear - which might feel annoying when upgrading, but is ultimately much less problematic down the road. --- pkgs/by-name/README.md | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/pkgs/by-name/README.md b/pkgs/by-name/README.md index 5f962ccffa01..fd0bd031b12d 100644 --- a/pkgs/by-name/README.md +++ b/pkgs/by-name/README.md @@ -62,16 +62,12 @@ The above expression is called using these arguments by default: ``` But the package might need `pkgs.libbar_2` instead. -While the function could be changed to take `libbar_2` directly as an argument, -this would change the `.override` interface, breaking code like `.override { libbar = ...; }`. -So instead it is preferable to use the same generic parameter name `libbar` -and override its value in [`pkgs/top-level/all-packages.nix`](../top-level/all-packages.nix): +While the `libbar` argument could explicitly be overridden in `all-packages.nix` with `libbar_2`, this would hide important information about this package from its interface. +The fact that the package requires a certain version of `libbar` to work should not be hidden in a separate place. +It is preferable to use `libbar_2` as a argument name instead. -```nix -{ - libfoo = callPackage ../by-name/so/some-package/package.nix { libbar = libbar_2; }; -} -``` +This approach also has the benefit that, if the expectation of the package changes to require a different version of `libbar`, a downstream user with an override of this argument will receive an error. +This is comparable to a merge conflict in git: It's much better to be forced to explicitly address the conflict instead of silently keeping the override - which might lead to a different problem that is likely much harder to debug. ## Manual migration guidelines