Sudden renames cause warnings in out-of-tree modules

[roberth]

Describe the bug

The current process for renames puts out-of-tree modules in a situation where users are confronted with warnings they can't solve, and neither can the maintainers.

Steps To Reproduce

Steps to reproduce the behavior:

1. In one change, create the new option/package/..., create the alias with a deprecation warning that goes into effect immediately
2. Out-of-tree modules, such as home-manager, nix-darwin, cachix use --nixos start emitting warnings
3. User reports warning
4. Out-of-tree module maintainer can't do anything, because stable release does not have the new option

Expected behavior

All generated warnings can be resolved by the user.

Suggested process:

1. In one change, create the new option/package/... and the alias but no deprecation warning
2. Some 1-7 months pass. All current branches now support the new way.
3. We enable the warning on master (more on that)
4. Out-of-tree modules, such as home-manager, nix-darwin, cachix use --nixos start emitting warnings
5. The warnings can now be fixed

To facilitate the process, we can add an argument to functions like mkRenamedOptionModule to indicate the first release that will support the change. We'll maintain two (hidden?) version numbers that we update during the NixOS release process. For example, at the time of writing, the only supported stable version is 21.11 and 22.05 has not been released yet.

# lib:
{
  oldestSupportedRelease = 2111;
  shouldEmitWarning = n: n < oldestSupportedRelease;
  mkRenamedOptionModuleWith = { sinceRelease, from, to }: doRename { warn = shouldEmitWarning sinceRelease; ... } 
}
# nixos:
mkRenamedOptionModuleWith { sinceRelease = 2205; ... }

To enable warnings on master, we only need to update oldestSupportedRelease.

Interestingly, we'll be deprecating functions that deprecate without sinceRelease. Sounds meta, but it's not complicated. It just means that some old style deprecations will slip through the net for some more time.

Screenshots

Additional context

nix-community/home-manager#2371 (comment)

#139075 (also a big one, but no complaints yet)

Notify maintainers

@jonringer @rycee @infinisil

[infinisil]

This is also related to NixOS/rfcs#33, which was a previous attempt at establishing general such deprecation behaviors