How to introduce a breaking version bump

[jtojnar]

@doronbehar

Keeping pkg1 along side pkg2 forever doesn’t solve the main issue I tried to present here - the fact that no body will be aware of the new version unless they’d check with upstream by themselves. In general, the fact that Nixpkgs fails to distribute the fact that there is a new version of a program (whether the new version is breaking or not) is a failure of the mission of the distribution in my opinion.

I still think this is what release notes are for. After all, we cannot distinguish whether user knows about the new version, and renaming the attribute just to let them know adds needless churn.

We just need to figure out how to make release notes work on unstable.

There is also, which might be useful: GitHub - trofi/nix-olde: Show details about outdated packages in your NixOS system.

@doronbehar

I was thinking of this way (imagine the version bump is from 1.5 to 2.0):

1. Create a new attribute pkg2 that points to the new 2.0 version.
2. Add the attribute pkg1 that points to the old 1.5 version.
3. Make the old pkg attribute that used to be 1.5 point to pkg1, but use lib.warn in aliases.nix, with a message indicating that upstream introduced a breaking change and in order to avoid this evaluation warning the user should knowingly transition to pkg2 by themselves.
4. After a few months, remove the lib.warn, and make pkg = pkg2;.

I would say this protocol makes sense for when the old attribute becomes deprecated (see also doc: add instructions to rename a package · Issue #142873 · NixOS/nixpkgs · GitHub). I think most people will agree warnings are the perfect method to let users know about deprecation in advance, without immediately breaking their configs.

Unfortunately, warnings also have side effects – they spam nix-env users, and I vaguely recall there was some issue with Hydra. Though, since warnings have been used in aliases.nix for a while now, perhaps Hydra is no longer a problem (it definitely should not be if we merge release: disallow aliases by jtojnar · Pull Request #316680 · NixOS/nixpkgs · GitHub), and nix-env spam might be considered an acceptable trade-off.