Documentation missing on when to add a warning to aliases

[quantenzitrone]

Reviewers have been giving conflicting reviews on package renaming PRs.

@gepbird @Hythera @magnetophon @wolfgangwalther @teto & @qweered have been telling to add warnAlias straight away:

• various: move to pkgs/by-name #479415 (comment)
• various: move to pkgs/by-name #479415 (comment)
• melonds: rename from melonDS #488477 (comment)
• lycheeslicer: rename from LycheeSlicer #488478 (comment)
• libbladerf: rename from libbladeRF, enable structuredAttrs & strictDeps #488485 (comment)
• surge-xt: rename from surge-XT #489651 (review)
• vimPlugins.pure-lua -> vimPlugins.moonlight #462405 (comment)
• mopidy{,Packages}: move into python Packages #468955 (comment))

@bjornfor has been telling, warnAlias should be added after one release cycle or after renames have been backported to stable:

• various: change aliases to warnAliases #489719 (review)
• source-highlight: rename from sourceHighlight, enable structuredAttrs #489656 (comment)
• libbladerf: rename from libbladeRF, enable structuredAttrs & strictDeps #488485 (comment)

Arguments for adding warnAlias directly:

• faster deprecation

  • Counter: deprecation is too quick

• Context of alias gets lost when aliases are converted to warnAlias
  manual rename message could be (e.g. source-highlight: rename from sourceHighlight, enable structuredAttrs #489656)

  "'foo' has been renamed to 'bar'"

  or (example from xdg-terminal-exec-mkhl: drop #480126)

  "'foo' has been removed due to reason, use 'bar' instead."

  automatic rename message would always be

  "'foo has been renamed to/replaced by 'bar'"

  -> the manual message is more clear

  • Counter: automatic message is clear enough
    second example pr doesn't create an unactionable warning so it doesn't count

Arguments for not adding warnAlias straight away:

• When unstable has a warnAlias and stable does not have the new package name, one cannot have a configuration or nixos module that works for both stable and unstable without having countless warnings on unstable.
  -> warnings are not actionable without breaking stable
  • Counter: you can just ignore the warnings
• @bjornfor remembers that in the beginning (when they started using NixOS) there were aliases, and eventually they became warnings/errors (after at least one release period). There even exists maintainers/scripts/remove-old-aliases.py, which is built upon the "alias -> warning -> error" flow. As far as they can tell, aliases were never meant to be direct warnings. Going straight to warning for aliases feels to them like some recent development, presumably by people running nixpkgs-unstable exclusively?

Additional Context

• The maintainers/scripts/remove-old-aliases.py script has relatively recently been adapted to the "alias -> warning -> error" flow maintainers/scripts/remove-old-aliases.py: convert aliases to warnings before throwing or removing; aliases: cleanup #427017

What now

I don't care a lot about whether aliases should be warnAliases or not, but getting conflicting reviews on PRs is shitty and creates a deadlock situation.
So either we come to some solution here together or we have to ask the nixpkgs core team or the SC.

[bjornfor]

I don't care a lot about whether aliases should be warnAliases or not, but getting conflicting reviews on PRs is shitty and creates a deadlock situation.

I'm sorry about the conflicting reviews situation, but I'd like to point out that there is a way out of the deadlock right now; split the PRs in two:

1. create alias
2. convert alias to warnAlias

The first one can be backported to stable immediately and then the deprecation cycle is just as fast as "direct warnAlias" on nixpkgs-unstable.

[wolfgangwalther]

Essentially the reviews are not conflicting. It's just that two things need to be taken care of: (1) Deprecate immediately and (2) provide the alias on stable.

This can either be done by splitting PRs - or by creating the PRs as-is and then backporting the creation of the alias immediately (not the warning, ofc).

[quantenzitrone]

Backporting package renames to stable seems weird.
While I can't think of any direct Problems this would create, since probably almost no one on stable runs allowAliases = false (probably only a few people on unstable as well), I have some doubts

• Could the package name changing on https:://search.nixos.org be something we are concerned about?
  Are non-changing package names in the package search for a release channel something that could be useful for or expected by people?
• I can think of PRs that this doesn't work for, when an added alias depends on a previous unstable-only PR.
  e.g. the whole xorg namespace deprecation.
  on nixos-25.11 xorg-server/xorg.xorgserver and a whole bunch of xorg packages are still defined in the horrible autogenerated xorg package set mess in pkgs/development/servers/x11/xorg/
  on unstable they have been refactored and moved to pkgs/by-name and the whole xorg package set has been aliased with warnings.
  Backporting the xorg package set deprecation without warnings, would require also backporting the "refactor and move to pkgs/by-name"-PRs.

An alternative solution could be to make the warnings actionable by adding other way aliases on stable.
So instead of backporting package renames we would create newname = oldname; aliases on stable for all oldname = warnAlias "beep boop" newname; aliases on unstable.

[wolfgangwalther]

An alternative solution could be to make the warnings actionable by adding other way aliases on stable.
So instead of backporting package renames we would create newname = oldname; aliases on stable for all oldname = warnAlias "beep boop" newname; aliases on unstable.

Yes, that makes more sense.

[quantenzitrone]

another idea:
a configuration option to silence warnAlias warnings