lib: deprecation, warnRenamed, release constants

[Profpatsch]

Introduce the concept of attribute deprecation.
A new library contains deprecation functions (for now only
renamedWarning) that annotate functions and print a deprecation
warning.

In order to manage time until a symbol is removed, we introduce release
constants that are used in the warning messages and contain release
names and dates.

The printed warning only uses a trace message at the moment, this should
be improved.

As an example, opusTools is renamed to opus-tools, with the
reasoning that the related vorbis-tools uses a different naming
scheme. Users on master will immediately get a warning, users of stable
channels can find out about the changed attribute from the changelog
when they update to a new release.

cc @edolstra @aszlig @vcunat

[mention-bot]

@Profpatsch, thanks for your PR! By analyzing the history of the files in this pull request, we identified @edolstra, @nbp and @7c6f434c to be potential reviewers.

[globin]

(bikeshedding) I'd prefer changing renamedWarning to warnRenamed.

Additionally using lib.warn adds a "WARNING: " prefix if you use it instead of builtins.trace.

[Profpatsch]

(bikeshedding) I'd prefer changing renamedWarning to warnRenamed.

Thanks, I was dissatisfied with the name myself.
See you in an hour? :)

[Profpatsch]

I remember seeing a checklist for releases somewhere. We should add “search and delete all that is deprecated in this version, add each item to the release notes; do it in one commit”.

[edolstra]

This has been tried before, but the problem is that it makes nix-env -qa print out lots of warnings (because it evaluates deprecated attributes).

[domenkozar]

@Profpatsch just landed in master at ed6ea74

[Profpatsch]

I’m not sure, I haven’t used nix-env for over a year I think. I hear it does … strange things. :)
Can we add some metadata it can use to find out about deprecations? I’d like to get rid of the special “skipping abort and error from nix-env sooner or later, it makes a lot of things very awkward.

[sternenseemann]

Still to do would be

• warnRemoved
• warnSemanticChange (new package behind the name etc.)

[rasendubi]

Shouldn't this be 17.09 (not 17.03)? If it's 17.03, there is no deprecation period for users of stable channels.

[Profpatsch]

not 17.03)? If it's 17.03, there is no deprecation period for users of stable channels.

When you update your stable channel you are expected to read the changelog and fix any evaluation errors that arise in one swoop. At least for renames it gives a nice evaluation error and will be documented in the changelog.

[vcunat]

Ref. about problems with nix-env: 8e8e23de33

[Profpatsch]

At the moment we only have trace as a way of putting stuff on stderr while evaluating. trace was originally designed to enable debugging, but has been abused a lot for warnings.

What do you think about introducing a warning <msg> builtin, which prints a yellow Warning: to stderr? Those can then be ignored by tools that want to strictly evaluate as much of nixpkgs as possible, and we get trace back for debugging, as was originally intended.
cc @edolstra @vcunat.

[vcunat]

Yeah, perhaps. Tools can filter those lines easily enough now (e.g. by a simple grep), though it's not perfectly reliable in principle.

[Profpatsch]

@vcunat With your changes to mkDerivation recently, do you think the things in this PR could work now?

[samueldr]

It's probably a bit late to get this together for 18.09, but I really think either this or something doing the same job is in need.

There were a couple sparks flying around lately with regards to deprecation of attributes;

We had a chat about something similar recently on #nixos. One main thing differed from your approach in the idea thrown around: instead of approaching the deprecation in two stages (deprecate, remove), add an additional step (pre-deprecate, deprecate, remove). The pre-deprecation step would allow through an opt-in configuration to get the warnings during the pre-deprecation period.

The three-step approach allows users not to worry with a deprecation warning stemming from some tooling they use. Imagine tool "A" using nix, and using the attribute foo which has just been deprecated for the next NixOS release cycle. The author of "A" may not be able to fix their tool in time with the release, and the now-deprecated option shows up in their user systems, somehow confusing them. Not the most amount of value for use inside nixpkgs, but probably much more for third-parties building solutions around nix and nixpkgs. (I know my users at $client would all let me know about a new deprecation warning!)

Let me know your thoughts about that additional step.

---

TLDR: 👍 want to see this or something doing the same job hit 19.03.

[Profpatsch]

instead of approaching the deprecation in two stages (deprecate, remove), add an additional step (pre-deprecate, deprecate, remove)

I wouldn’t overcomplicate it, someone has to remember to change these after all. I haven’t seen systems that do it like this so far. Maybe the overhead is not worth the gains in practice..

[edolstra]

What really is the need for removing compability aliases? It doesn't really cost us anything to keep an alias like opusTools = opus-tools around.

Also, removedAt = lib.releases.next is inherently stateful - if people actually write that, it would mean the package would never be removed since its removal is always in the future. (Or you would have to consult the Git history to see when the removedAt line was first added.)

[samueldr]

I am operating only under the assumption that there is a need or want to remove compatibility aliases.

Though, something similar would be needed if something is going to be dropped, right? Dropping something from Nixpkgs will cause issues to the end-users (we can easily manage the change inside Nixpkgs).

---

About complicating with pre-deprecation:

This is for end-user user-friendliness. The warnings will cause headaches to the end-user using additional tools built on top of nixpkgs. The integrator (a nixpkgs user that built the tool built on top of nixpkgs) would be expected to follow up with the news (reading the release notes, hoping it made it in) or better with the option, using the the option opting-in for the warning one release beforehand. This is not for the simple "nixpkgs and nixpkgs users" situation, but one that has to be thought of, users using tools built by other users of nixpkgs.

---

I will add a bit, and maybe be a bit harsh:

Let's not stop or stall the discussion about the deprecation feature because there is no need since we can keep compatibility aliases. Please either review under the assumption the feature being implemented in whole is required and needed, or reject the feature as a whole if undesirable. Right now the half-rejection-because-we-keep-everything makes this a less desirable feature to look at and work on since there's a heavyweight decision maker casting a negative cloud over the future of the feature.

In the event the feature is desirable only or some uses, and a technical solution does not exist restricting its use (e.g. dropping aliases for renamed attributes), it'll have to be documented and rely on the committers/members to review appropriately.

[mmahut]

Any updates on this pull request, please?

[Profpatsch]

Don’t think this will ever happen. Thanks for triaging.