Deprecation

The art of making a change with minimal impact to users.

Ideal flow

• Add new method. Wait for new method to be available in all supported releases (see "3rd party" section below).
• Add a deprecation warning to the old method. Provide migration guidance.
• Replace the old method by an exception. Move the migration guidance to the error message.

Minimizing impact on 3rd party repos

Besides the user and nixpkgs, 3rd party repos like home-manager and many others provide expressions. These generally need to be compatible with not just master but also the stable release(s). If possible, a window during which both old and new solutions are available should be provided, to avoid warning fatigue and github issues about warnings.

Tools for automating this process: see oldestSupportedRelease and isInOldestRelease in lib/trivial.nix

Some more guidance on using this automation would be helpful.