Currently WIP because I haven't finished going through all of the mentions of packageOverrides in the manual.

Unless supporting packageOverrides imposes severe hardship on us, we should not remove it. We shouldn't get in the habit of unnecessarily breaking people's configurations.

Also, we really shouldn't spam people's consoles with huge walls of text via lib.warn. If it's really necessary to warn people, it should be a short reference to the manual.

(disadvantages of packageOverrides copied from my original description in #43266)

• Learning/documentation overhead. We have 3 distinct things with the word override in them: packageOverrides, pkg.override introduced by callPackage, and pkg.overrideAttrs introduced by stdenv.mkDerivation. This is very confusing to beginners (it was to me as well, and we didn't have overlays at the time). Additionally, packageOverrides shares a space with overlays while being less powerful.
• Unwieldy composition. I seem to recall there being some trick involving something like self: let super = self.pkgs; to get an approximation of what overlays provide, but it inrtoduces a fixpoint in each layer AFAIU. I personally don't know exactly how this works, but overlays are pretty clear in this respect.

To elaborate on the former, we constantly have new users coming in and being confused by packageOverrides. Typically this is because experienced users of nixpkgs are still using them and recommend using packageOverrides to solve some problem, even if the new user is already familiar with overlays. This creates the mostly false impression that packageOverrides is something they need to know about (when it's actually just a less powerful version of overlays and overlays are more worth knowing about). I enjoy helping people with nixpkgs, but not so much having the same stumbling blocks every time (and the nix ecosystem unfortunately has its fair share of these), which is why I want to remove this one.

As far as the warning is concerned: so move what I wrote into a subsection of the overlays chapter and link to that in the warning? Personally I'd prefer not to go through the layer of indirection of opening my browser, but it's not a hill I'll die on. As for whether the warning should be there at all, I'd consider it polite to let users know (but keep them working) in 18.09 before removing it in 19.03 or something like that.

@edolstra :

Unless supporting packageOverrides imposes severe hardship on us, we should not remove it. We shouldn't get in the habit of unnecessarily breaking people's configurations.

Simplifying the problem we are working with while moving towards something which has more feature with a simpler model sounds like a good goal.

Deprecating a feature for X versions before removing it is a good way to know what are the problems, and improve the documentation to migrate from the old scheme to the new one.

If we do not allow to change existing features, then we are left with only adding complexity. This can only result in tools which are harder to understand and to use properly.

Yes this is good, and lib.warn is also good because people shouldn't have to do extra work to learn what's going to be removed; the point of "deprecation" to do that work for them so they can just focus on finding the time to avoid using the deprecated item.

One valid objection to overlays in general, voiced by @grahamc on IRC, summarised by me (see https://logs.nix.samueldr.com/nixos-chat/2018-07-16#1380939 for what he wrote himself):

Overlays invariably work in the scope of all of nixpkgs, and can thus have wide-reaching, potentially undesirable effects. In addition, the composability encourages mixing and matching overlays from arbitrary sources, while an individually curated packageOverrides function forces a user to define what modifications are applied to nixpkgs more precisely.
</attempt-at-paraphrasing-graham>

Personally I think that in practice this isn't much of an issue — poor-quality overlays aren't too likely to become popular I suspect, and malicious individual packages can do just as much damage as a malicious overlay.

Are there any updates on this pull request, please?

Probably needs an RFC.

Thank you for your contributions.
This has been automatically marked as stale because it has had no activity for 180 days.
If this is still important to you, we ask that you leave a comment below. Your comment can be as simple as "still important to me". This lets people see that at least one person still cares about this. Someone will have to do this at most twice a year if there is no other activity.
Here are suggestions that might help resolve this more quickly:

1. Search for maintainers and people that previously touched the
   related code and @ mention them in a comment.
2. Ask on the NixOS Discourse. 3. Ask on the #nixos channel on
   irc.freenode.net.

I guess I still need to write that RFC :)

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/why-are-overlays-better-than-pkgoverrides/7052/12

packageOverrides occurs 46 times in the Nixpkgs manual, whereas overlay occurs 92 times.
The NixOS manual is 'worse' with 5 occurrences of packageOverrides and only two overlays.

Documentation is actually the biggest problem here. If we update that, newcomers will probably never learn about packageOverrides. Deprecation only serves to make old codebases accessible to newcomers, but with the current documentation that's hard to argue.

I was going to update all the documentation in this PR, but given Eelco's opposition to this I didn't want to invest the effort for nothing. Maybe One Day™ I'll write an RFC or something.

We shouldn't get in the habit of unnecessarily breaking people's configurations.

But a warning is not breaking any code? Everyone would get time to adopt, right?

Eelco's opposition

I'm not sure if I followed the discussion correctly but I don't understand why a proper proposal of

Simplifying the problem we are working with while moving towards something which has more feature with a simpler model

is not progressing?

• What exactly are technical reasons to stop the improvement?

As kind of a new nix user I would be interested in more simplicity and streamlining to efficient methods like overlays.
FYI: my config is changing/"breaking" all the time (because nixos/nix is progressing in many ways with quite some velocity)
-> I think nixos/nix user are used to changes and welcome those.

I marked this as stale due to inactivity. → More info