lib/helpers: add deprecation.mkTransitionOptionModule

[MattSturgeon]

helpers.deprecation.mkTransitionOptionModule is similar to lib.mkRenamedOptionModule, however it instead warns users that the option was renamed to avoid confusion, and will eventually be transitioned to the new option.

The implementation is basically identical to lib.doRename.

This is intended as one possible solution to #1371 and #1352.
If we go down this route, we would introduce the new plugins as -nvim variants, rename the old plugins to -vim and add a transition alias warning users that the un-suffixed name will transition to the -nvim option.

• Users with plugins.surround in their config would get a transition warning.
• After we transition, we'd also need to maintain a surround-nvim alias
• That alias could eventually switch to a rename (with warning)
• We might also want a post-transition warning, telling users the transition has happened.

---

I've tested this by adding the following to surround.vim's imports and changing name to "surround-vim":

imports = [
  (helpers.deprecation.mkTransitionOptionModule {
    from = [ "plugins" "surround" ];
    to = [ "plugins" "surround-vim" ];
    future = [ "plugins" "surround-nvim" ];
    takeover = "2024-09-09";
  })
];

This produces the following warning when used with a config that contains plugins.surround.enable = true:

trace: warning: The option `plugins.surround' defined in `/nix/store/lylx2xpibp09k24ihrkf8pyn22kv0kcf-source/nvim/config/main.nix' has been renamed to `plugins.surround-vim'.
This has been done to avoid confusion with the new option `plugins.surround-nvim'.

At some point after 2024-09-09, `plugins.surround-nvim' will be moved to `plugins.surround'.

It's a shame multiline trace warnings are so ugly, so I'd appreciate suggestions for making it more readable. The first line of the warning is based on the warning used by lib.doRename.

[traxys]

Maybe we should use NixOS releases as takeovers globally in nixvim?

[MattSturgeon]

Maybe we should use NixOS releases as takeovers globally in nixvim?

I agree, I think that'll make things easier for stable users upgrading and we'll also have an obvious reminder of when we need to go through and remove old deprecations.

Although, personally I'm in favor of not removing old deprecations where possible.* Instead we could move them somewhere less obnoxious, like ./warnings.nix files?

* e.g. you can't avoid a transition warning needing to be removed when future takes over from's path.
* or if we can't find a less obnoxious way to maintain the warning (e.g. keymaps.*.lua), then removal is fine.

[MattSturgeon]

Left some comments for discussion of the actual code.

But I don't think this should be merged until after we all agree on how we should handle the kinda name conflicts this helper attempts to resolve (i.e. #1371 and #1352). Otherwise we've just got dead code laying around!

Happy to discuss here or on matrix.

[MattSturgeon]

I've scoped this for now. Would you rather it be a top-level helper?

[traxys]

I think scoped is nicer

[MattSturgeon]

This should produce useful error messages when used incorrectly:

Suggested change

	opt = getAttrFromPath from options;
	toOpt = getAttrFromPath to options;
	in
	get = path: attrByPath path (abort "mkTransitionOptionModule: can't find option `${showOption path}`") options;
	opt = get from;
	toOpt = get to;
	in
	# Also assert `future` exists
	# get will abort before the assert does, only used to force it to evaluate
	assert (get future) != null;

[MattSturgeon]

See #1657 (comment)

Suggested change

	# The date or release after which `future` will be moved to `from`.
	# The nixos release after which `future` will be moved to `from`.

?