Have official policy for deprecating packages

[domenkozar]

@jophish on IRC just got bitten by using old texlive.

We should have a policy and a way to inform users of deprecated packages (including when they'll be removed).

[bobvanderlinden]

Same for PopcornTime. We needed to remove the package, but there is no standardized way to let users know that it was actually deprecated nor why.

@copumpkin suggested to replace the package expression with an throw "Removed from nixpkgs. See {url to pull request}"

Maybe create a deprecate function that does the same, but in a more standardized way?

[copumpkin]

A while ago, we were talking about cordoning off a separate section that lets us see all deprecated packages in one place.

{
  pkgs = import ./all-packages.nix // ./deprecated-packages.nix;
}

Or something like that. The message would be standardized across all deprecated packages, and probably just mapped over the attrset, with each value possibly providing more detail as needed.

[FRidh]

Two scenario's:

1. The package is going to be removed but is still included. We want to present a warning, and should include the date/release that it will be removed. Maybe also include when this was decided.
2. The package has already been removed, and users might be surprised to see it gone. Here the user wants to know what is going on.

Possible solutions:

1. A deprecate function that present a standard message, and takes a derivation, dates, and possibly a custom message to be added.
2. A deprecated function that throws a message

I don't think you can always refer to a PR or commit, because typically that commit would be the deprecation/change itself.

[dezgeg]

I think the throw method was tried at some point, but that didn't work as that message would pop up every time nix-env -qa were run.

[vcunat]

Once I tried hard to find a way (8e8e23d), but I just gave up, as it's really tricky to determine when to print the message and when you'd just spam someone who didn't really use the deprecated stuff directly.

[domenkozar]

So this discussion is about two things:

1. how to issue deprecation warnings in Nix
2. policy (namely when certain deadlines are met in deprecation timeline)

The way I see it 2) can be easily in pair with NixOS releases once we figure out a sane way for 1)

[joelmo]

I think it would be fine to print the deprecated dependencies regardless when building a package. I agree that deprecations deadlines should be for one or more NixOS releases. I also want to add that NixOS declares deprecations in a file, so having deprecated-packages.nix would be familiar and possibly easier to maintain. Just git blame and remove the lines older than release x, or a fixed time if it will be decided that the deadline is fixed for example 1 year.

[domenkozar]

There's a PR that partially implements this: #19315

[Profpatsch]

I’ll close this in favor of #19315.