Release plan for Lua rewrite

[wincent]

Here's an issue for me to think through the details of actually releasing the Lua rewrite (#380) that is going on right now in the pu branch.

• Current state:
  • Latest release is v5.0.4, cut from main branch on 28 May 2022. Implementation is in Ruby, compatible with both Neovim and Vim.
  • In-progress rewrite in Lua is happening on the pu ("proposed updates") branch; at the moment, it co-exists with the Ruby code: all existing commands (eg. :CommandT), mappings and settings point at the Ruby implementation, and completely separate (and temporary, and undocumented) commands (eg. :KommandT) trigger the Lua implementation.
  • Huge gotcha: given the way most people in the Vim/Neovim install plug-ins (by tracking main/master and periodically updating to the latest HEAD without consulting release notes or changelogs), SemVer is basically useless.
• Desired end state (ideally):
  • Everybody who uses Neovim gets to use Lua implementation with no downside; switching to it should be easy, or even automatic, as part of a regular upgrade.
  • Users who continue with Vim, or for some reason wish to continue using the Ruby implementation, can do so at low or no cost. (Note that keeping the Ruby version around is useful, or at the very least it's interesting, for me as a developer because it enables me to keep a working alternative implementation around for the purposes of doing comparative benchmarks.)
  • Maybe, in some distant future, the Ruby implementation gets removed in order to simplify the codebase (ie. instead of having to manage what are effectively duplicates, we just manage the newest incarnation) and the documentation. Even if we don't remove it, it will pretty much be unmaintained, with only critical bugfixes considered. As such, the intent is to keep the cost of having it stick around relatively low.
  • Disclaimer: full feature parity is not a goal, as part of the motivation here is to do some spring-cleaning and make a leaner, meaner codebase. One of the ways in which this clean break is going to be communicated is that options will not be shared across the two implementations. That is, while the Ruby version used globals like g:CommandTMaxFiles, the Lua version will follow the Lua idiom and instead expect people to call the setup() function (eg. with something like require'wincent.commandt'.setup{max_files = ...}).

Given the above, this is what I provisionally think I'm going to do:

• Point 5-x-release and 5-x-devel branches at current main branch. Whatever happens, people who don't wish to accompany me into this brave new world can remain in the old one by tracking those branches instead. (Technically, they should track 5-x-release, which is the "stable" version of the 5.0.x series, corresponding to actual releases.)
• Keep the Ruby version in-tree in both pu and main indefinitely (or until some change in a dominant platform like macOS makes keeping the build alive too painful to continue).
• When running in Vim, always load and use the Ruby-powered implementation. That is, commands like :CommandT and so on will map onto the Ruby underpinnings.
• When running in Neovim, attempt to load the Lua-powered implementation and use it when users run commands like :CommandT or use standard mappings. Specifically, the transition plan should look something like this:
  • Once the Lua version is feature-complete and solid enough for us to merge pu into main, start printing a deprecation notice for the Ruby version; let users opt-in to the Lua version with a setting, or suppress the deprecation notice and stick with the Ruby version by applying an inversion setting. This setting might be something like let g:CommandTPreferredVersion='ruby' to opt-in to the Ruby version, or require'wincent.commandt'.setup{} to opt-in to the Lua one. It's possible I might want both of those to be expressible in negative form too, to make load order a bit more flexible (eg. let g:CommandTPreferredVersion='lua' could work from Vimscript, just as vim.g.CommandTPreferredVersion='ruby' or require'wincent.commandt.setup{ruby=true} could work on the Lua side).
  • Around the same time we reach that "feature-complete and solid" threshold, get rid of the :KommandT family of hack commands, which really only exist for me to be able to test the new implementation while simultaneously working inside Neovim and using the original implementation to get work done.
  • "Fork" the documentation, if that's a legit thing to do (I'm not sure if it is... it's not something I recall seeing other plugins doing, but Vim's own documentation is split into many different files). The idea here is to make the documentation maintainable and more accessible by splitting it into two files, the main/Lua documentation (doc/command-t.txt) and the legacy/Ruby documentation (maybe doc/command-t-ruby.txt). For sense of the kind of names Vim/Neovim uses, see :e $VIMRUNTIME/doc; in short, they are all short names with underscores and a .txt extension (eg. intro.txt, nvim.txt etc) — they're all findable because they have tags like *message.txt* at the top.
  • The above might happen in v6.0.x seeing as a new deprecation notice requiring user action to suppress it is technically a breaking change.
  • In v7.0.x the notice could go away, at which point we would try to use the Lua version automatically in Neovim (when running in Vim we could continue to use the Ruby implementation). In this case, if you hadn't built the C library, you'd get instructions on how to do so. There would ideally be at least 12 months between v6.0.x and v7.0.x, to give people plenty of time to be alerted, and also because in theory the "hassle" of being in a transitional state shouldn't be that great for me as a developer.