UPDATE

Looks like either I missed something when I wrote this issue, or nixpkgs has changed in the meantime.
Anyway, current pkgs is self and current self is the next stage's super.

Old Issue

Issue description

The pkgs/top-level/all-packages.nix is essentially an overlay, but its parameters are called self and pkgs, which is wrong. self in that file is actually what is normally called super and pkgs is what is normally called self.

This causes confusion.

I suppose this itself is a legacy problem and changing these names will break many nixpkgs forks. Fixing this straight away will produce problems that are not easy to relate to this change, so I suggest we follow a simple migration plan

Steps to reproduce

Try to use self.runCommand in all-packages.nix.

or

Add a line xself = self; and run

$ nix-instantiate --eval --expr '(import ./. {}).xself.runCommand'
error: attribute ‘runCommand’ missing
$ nix-instantiate --eval --expr '(import ./. { overlays = [ (self: super: { foo = true; }) ]; }).xself.runCommand'
error: attribute ‘foo’ missing

Migration plan

1. Rename to pkgsSelf and pkgsSuper; create aliases for self and nixpkgs that emit warnings using builtins.trace.
2. Remove the aliases.
3. (optional) Alias pkgsSelf and pkgsSuper to self and super.
4. (optional) Remove pkgsSelf and pkgsSuper.

Code:

0. self: pkgs:
1. pkgsSuper: pkgsSelf: let pkgs = deprecated pkgsSelf; self = deprecated pkgsSuper; in (yes, the parameters are in flipped order)
2. super: self: let pkgsSuper = deprecated super; pkgsSelf = deprecated self; in
3. super: self:

where deprecated is a meta-expression that represents the identity function with the side effect of emitting the right warning using builtins.trace. (I've omitted the actual warnings for conciseness)

Of course, the contents of all-packages.nix will be updated to reflect the current best practice with each of these changes.

We might also want to fix the mysterious flipped parameter order. (Which may have been caused by an implementation detail of the overlay fold that was used?) This should be easier to fix, because it would only break forks that introduce new hardcoded overlays (in stage.nix instead of via the 'public' overlays parameter in /default.nix etc)

I'd love to hear what you think.