Guidelines for adding new plugins and their maintenance

[lackac]

I was configuring vim.assistant.avante-nvim last week and noticed that it lists so many options under setupOpts but there is no special implementation or translation for any of those. In this case they serve mostly to document the possibilities. I wonder if this was done on purpose and if there is a preference for treating plugins this way.

The other approach is a plain setupOpts only introducing options if there are exceptions (custom defaults or transformations).

I see pros and cons for both approaches:

Minimal setupOpts makes it easy to add support for new plugins lowering the barrier for contributions and also simplifies maintenance since there is not much to keep in sync with the development of the plugin. But this approach leaves it to the user to go and find the documentation of the plugin at the source and translate the lua configuration into nix for the things they want to change. Linking to the website of the plugin from the documentation of the enable option could help with this.

Detailed setupOpts adds more maintenance burden mostly on the documentation side and makes it more difficult to upgrade a plugin in case of breaking changes like the recent vendors to providers move for avante. But it also makes it easier for users to search for the available options in nvf's documentation and the examples are usually helpful in complex cases where mkLuaInline is involved.

In most cases it makes sense to start with the first approach and gradually move towards more documentation as time allows.

A slightly related question is the matter of plugin upgrades. When using the minimal approach in most cases it only takes updating the plugin in npins, but that might cause breaking changes in user configurations which are not visible and could be difficult to detect and document. With the detailed setupOpts approach breaking changes that affect the configuration of the plugin are more visible and will make it necessary to use mkRemovedOptionModule or mkRenamedOptionModule.

I'm looking for guidance around these matters possibly as a section at https://notashelf.github.io/nvf/index.xhtml#ch-hacking

[NotAShelf]

I was quite positive that I've responded to this. Must be the old age getting to me...

The agreed upon decision, although never formally codified, is that we should not overpopulate setupOpts as upstream tends to change, and force us to periodically update our configuration--thus creating a major maintenance burden. This creates one problem however, which is that users may not always know which Nix types translate to the Lua expressions they are looking for. As such we came to the compromise that minor plugins receive empty setupOpts sets ({}) and large plugins receive some setupOpts attributes that serve more of a documentation purpose than anything else.

Detailed setupOpts adds more maintenance burden mostly on the documentation side and makes it more difficult to upgrade a plugin in case of breaking changes like the recent vendors to providers move for avante. But it also makes it easier for users to search for the available options in nvf's documentation and the examples are usually helpful in complex cases where mkLuaInline is involved.

This is true, but I am more in favor of requiring module additions to document particularly complex module options, for two reasons

1. Is the inherent testing that comes from simply working with the Nix values that will be converted in a live config
2. Having a place to document necessary tips or requirements, specifically in the description field so that the users don't have to try and look up previous issues or discussions.

A compromise could be to avoid setting a default value, but that leaves the issue with type which I am not entirely sure if we can remove. In the mkOption implementation there are no checks for whether type is undefined, so perhaps this could serve as a way that allows to only document options. Though, that causes us to supply outdated documentation. I don't have a strong opinion on the matter, so we can discuss this further.

A slightly related question is the matter of plugin upgrades. When using the minimal approach in most cases it only takes updating the plugin in npins, but that might cause breaking changes in user configurations which are not visible and could be difficult to detect and document. With the detailed setupOpts approach breaking changes that affect the configuration of the plugin are more visible and will make it necessary to use mkRemovedOptionModule or mkRenamedOptionModule.

I have two ideas in mind to remedy this issue. The first one, which I've been working on for a while now, is the machine tests. I intend to start with tests for flake packages (i.e., those packaged in our flake.nix insted of being constructed from npins) and then move on to packages that are known to break often. I Currently working on a small change to the structure of the packages output, and I'll make a small addition to the "hacking" chapter while I'm at it to document how to add & update those kinds of packages. Also open to more suggestions or discussion if you'd like to add anything else.

CC @horriblename for his input on the matter. For v0.8 we may consider getting rid of all default types and values, but that'd delay the release further.

[horriblename]

Most of my opinion is close to raf's so just I'll keep this short

I lean heavily towards having a minimal setupOpts, though complex options should be documented in some form. mkOption with no default or type is an interesting idea we can explore.

For v0.8 we may consider getting rid of all default types and values, but that'd delay the release further.

that's a big fat invisible breaking change I'd rather not touch

[lackac]

Looks like it was my turn to forget to update here…

Thank you both for your thorough responses. I think we are aligned on the approach and it's good to get clarity on that. It might be good to distill this into a section in the hacking chapter. Let me know if you think that's a good idea and I'll create a draft.

Anyway, thank you for the great work. I'm looking forward to seeing the languages overhaul work finished (I've been using that for the last week without any issues).