top-level/aliases: split into files by release

[wolfgangwalther]

This is a first step towards better aliases. With this split, it will be dead-simple to drop all aliases created in a certain release at once - no need for a fancy script anymore. The script is still kept, because it should also work on other, non-migrated, alias files, I assume.

The idea is to:

• Keep lib.warnOnInstantiate for max 1 cycle and convert to a throw afterwards.
• Keep throws for two full stable releases. That means a throw added today (in 25.11), will be kept for 26.05 and 26.11 and will be dropped in the 27.05 cycle.
• Always add new throws in the latest file.

Addresses a tiny bit of #441108 (comment), aka only the "date vs release" thing.

This step should play nicely with both the current style of aliases as well as "structured aliases" described in the linked comment.

@emilazy WDYT?

Things done

• Fits CONTRIBUTING.md, pkgs/README.md, maintainers/README.md and other READMEs.

---

Add a 👍 reaction to pull requests you find important.

[emilazy]

I’d thought about this. My hesitance is that we don’t want all aliases to be in these files, because package sets exist, so there are always going to be inline aliases, so we need a solution for those. Of course handling the common case is nice, too… I suppose as long as we get a way to have CI fail when there are aliases that should be removed anywhere, having a script that handles the common case and doing the rest manually is an improvement. So, yes, I think this is an incremental improvement.

I have more fleshed out ideas for how to handle the mkAlias stuff after sleeping on it, but I will put those in the other PR, which is clearly the best place to be having this discussion, to avoid derailing this.

You will want to adjust/remove/whatever maintainers/scripts/remove-old-aliases.py, which we basically don’t run in practice because it likes to break eval and also we don’t warn on most non‐throwing aliases so the deprecation process there kinda sucks.

My biggest nit to pick: let’s key the files on the release they were added, not removed; pkgs/top-level/aliases-25.11.nix and so on. That prevents having to think when adding them, which is far more common than dropping them. I’m also not a fan of how you want to add warnings to aliases.nix and then migrate them later, but, future work.

Also the comment in aliases.nix needs adjusting to give correct advice.

• Keep throws for two full stable releases. That means a throw added today (in 25.11), will be kept for 26.05 and 26.11 and will be dropped in the 27.05 cycle.

Personally I think one stable release is fine, but I’m not picky. I guess this is the “upgrading from oldstable during the overlapping support window” thing.

[wolfgangwalther]

My biggest nit to pick: let’s key the files on the release they were added, not removed; pkgs/top-level/aliases-25.11.nix and so on. That prevents having to think when adding them, which is far more common than dropping them.

That was my first idea, too, but this will make it very annoying to backport things - the file in which you'd need to add an alias would always change. However, with this approach here, backports would use exactly the same files on both branches.

Edit: Also, it will allow better error messages, because we can fill these structured aliases with the info "will be dropped in XX.YY" in one go.

I’m also not a fan of how you want to add warnings to aliases.nix and then migrate them later, but, future work.

That's just an intermediate thing right now. I would like to add warnings to the newest drop file (one newer than currently exists - Edit: Or the newest one currently available? Couldn't make my mind up, yet), but I had to stop somewhere reasonable at this stage.

[wolfgangwalther]

Another approach entirely: If we provide the various mkAlias functions discussed in #441108, then maybe aliases should just be in by-name as:

{ mkRenameAlias, renamed-package }:
mkRenameAlias "25.11" renamed-package

This would also be considerably simpler to maintain script-wise, because "delete the whole folder" is rather simple to do, compared to dealing with these comments and replacement and whatnot.

Also, do we really want that huge alias.nix file? We should make aliases first-class.

[emilazy]

That was my first idea, too, but this will make it very annoying to backport things - the file in which you'd need to add an alias would always change. However, with this approach here, backports would use exactly the same files on both branches.

Usually you shouldn’t be backporting an alias like that, though? Like, for instance, we should not backport an alias that adds a warning to a stable branch. For things like renames, it actually makes sense to have an “aliases added in 25.11” file on the 25.05 branch, that explicitly omits the warning on 25.05, because the release is lower than when the deprecation period started.

Another approach entirely: If we provide the various mkAlias functions discussed in #441108, then maybe aliases should just be in by-name as:

{ mkRenameAlias, renamed-package }:
mkRenameAlias "25.11" renamed-package

With my idea, they’d be under __aliases, not the top level, so I guess we’d need an aliases-by-name type thing? It would be nice for avoiding merge conflicts, at least (see also: release notes).

You actually want to use a string for the rename, because the warning/throw should tell people the attribute path, and you can’t infer that from the package value in the general case.

[wolfgangwalther]

With my idea, they’d be under __aliases, not the top level, so I guess we’d need an aliases-by-name type thing? It would be nice for avoiding merge conflicts, at least (see also: release notes).

Merge conflicts are one thing, yes. But we should really try to put them into the general by-name folder, which would make some things easier. For example, we wouldn't need to check for conflicts between aliases and package definitions anymore etc. - we should really treat by-name as the authoritative source of naming down the road.

Usually you shouldn’t be backporting an alias like that, though?

I thought so, too, but then I looked at https://github.com/NixOS/nixpkgs/commits/release-25.05/pkgs/top-level/aliases.nix.

Like, for instance, we should not backport an alias that adds a warning to a stable branch. For things like renames, it actually makes sense to have an “aliases added in 25.11” file on the 25.05 branch, that explicitly omits the warning on 25.05, because the release is lower than when the deprecation period started.

That.. sounds sensible.

[emilazy]

Merge conflicts are one thing, yes. But we should really try to put them into the general by-name folder, which would make some things easier. For example, we wouldn't need to check for conflicts between aliases and package definitions anymore etc. - we should really treat by-name as the authoritative source of naming down the road.

Sure, makes sense to me. Standard by-name caveat, though: you actually need to do { mkRenameAlias, ... }@args: (mkRenameAlias "25.11" "renamed-package").override args for renames, which sucks.

Scattered thoughts:

• lib.warnOnInstantiate already returns an appropriate “dummy derivation” for rename aliases. We can just attach a meta.isAlias and ensure callPackage warns appropriately when it’s used.
• We still need to handle aliases to package sets, and those ought not go in by-name.
• Similarly, we can do a lib.throwOnInstantiate for throwing aliases. This isn’t going to catch builtins.seq pkgs.some-throwing-alias 123, though, even if we make callPackage smart about forwarding on the throw. I don’t know how much it matters to catch that before the hard removal.
• We’re limited in how much we can make warn or throw by whatever nix search looks at. Ideally nix search would not be bad, but oh well.
• If we can make warnings reliably happen, do we actually need !config.allowAliases given that we have NIX_ABORT_ON_WARN=1?

[wolfgangwalther]

Superseded by #442066, which I like a lot more.