Deprecation strategy

[MattSturgeon]

Currently we have a number of renamed and removed options, as well as a handful of more complex deprecation implementations throughout nixvim.

Most of these are tagged with a TODO comment, along the lines of "added 2024-09-06; remove after 24.11", however most of these deprecations have no negative impact, other than being an eyesore when reading plugin implementations.

I'd like to propose we adopt a pattern of "hiding away" these deprecations in a dedicated file, so that they can be left persistently, with (by default) no removal date at all.

Of course, in more nuanced cases, we would still remove a deprecation that has a) been around long enough to bridge stable versions and b) cause us issues in some tangible way. But warnings that do no harm should not need to be removed, purely for the sake of keeping things tidy.

Instead, we can achieve tidiness by doing something like this in plugin modules:

imports = [ ./deprecation.nix ];

And then having our usual deprecations in that separate module file:

{ lib, ... }:
let
  basePluginPath = [ "plugins" "hello" ];
  settingsPath = basePluginPath ++ [ "settings" ];
in
{
  imports =
    with lib;
    mapAttrsToList (old: new: mkRenamedOptionModule (basePluginPath ++ toList old) (settingsPath ++ toList new)) {
      hello = "world";
      foo = [ "bar" "baz" ];
    };
}

This would probably involve making use of lib.nixvim.mkSettingsRenamedOptionModules more often, without using the optionsRenamedToSettings argument in mkVimPlugin and mkNeovimPlugin.

This would also tie in nicely with plugins/by-name's proposed policy of always having a dedicated directory for each plugin, since we will be able to easily add ./deprecation.nix files, without having to convert foo.nix into foo/default.nix.