v2.0 breaking changes refactor

[stevearc]

If you wish to discuss any piece of this refactor, file an issue (please check if there is already one open for this topic first). This will help me to keep the discussions somewhat organized.

Preamble

I've been wanting to make big changes for a while, but I have had very little time for open source work since becoming a parent. Eventually I realized that if I gave up trying to make everything backwards-compatible, I could cut the time in half or more. Giving up backwards compatibility is not a decision I make lightly, but it is the only way I could get this done at all. I apologize to any users that have a rocky experience due to the update. I do not expect something like this to happen again, and hopefully you will find the changes worth it. I am planning to merge this mid-late November.

The goal was to get rid of unnecessary complexity, make simple things easier, and reduce the overall maintenance burden.

Big breaking changes

• Getting rid of third-party task strategies (e.g. toggleterm).
  • Overseer relies on controlling the terminal in order to provide tight integration and nice UI tools. If some other plugin (e.g. toggleterm) owns it, this creates bugs and a giant headache. These integrations have been the source of a lot of maintenance burden, and given that I don't use them I find the cost to not be worth the benefit.
• No more bundles (e.g. "save to bundle", "load from bundle").
  • We're still going to keep the serializability of tasks, but I no longer think the bundle workflow specifically is that useful. The underlying functionality is still present and is used for session save/restore. If you really miss bundles, you can build something like it on top of the API.
• Output parsing logic using behavior trees has been replaced by functions
  • When I began overseer, I put a lot of emphasis on making sure that every part of a task could be serialized and saved. This behavior tree system allowed for structured data to describe quite complex parsing behavior, so it seemed like a good fit. I have since decided to relax the serializability constraint, and with that it has become obvious that the syntax and functionality of this system are arcane at best. I've ripped it out in place of simple functions. They are so much easier to understand, debug, and write.
• Keymap syntax has changed
  • I've been iterating on the keymapping logic across all my plugins, and I have found this new format to be easier to use and more flexible than the old <Plug> style mappings.
• drop support for nvim <0.11

A longer note on serializability:
I tried really hard to make everything serializable at the beginning because it unlocks some cool features: session save/restore and saving/loading tasks in bundles. I found that the vast majority of the time I was using overseer for either one-off disposable tasks (e.g. grep) or simple templated tasks (e.g. make). It was extremely rare that I would both live-edit a task in any meaningful way and want to save it to disk. Two things changed: I added a new form of serialization that would handle templated tasks better, and I found bundles to not be useful. These two combined meant we could be overall a lot more relaxed about putting non-serializable data types (like functions) in components.

Smaller breaking changes

• The shell template has been deleted
  • This was mostly useful to add a quick shell one-liner in run_after or orchestrator, or to do :OverseerRun -> shell -> run a command. Now run_after and orchestrator can just pass in raw task arguments instead of going through the shell template, and to run a shell one-liner with Overseer there is a new :OverseerShell command.
• Most task template params have been removed
  • I established a pattern for most task sources of making a generic task with a parameter. For example, a general make task with an args parameter. Then other tasks could use wrap_template to wrap it and provide a default argument (e.g. make test). The idea was that this generic task makes it easier for the user to add custom configs that can run make <custom param>. Turns out, this is almost never done and adds a lot of complexity. So we got rid of all these unnecessary parameters.
• Changed task sorting and made it configurable
  • The default sort for tasks is slightly different now, and it can be configured. The default order for overseer.list_tasks has also been changed, and is different (simpler) from the default display sort order.
• Changed task rendering and made it configurable
  • The default appearance of tasks in the task list has been refreshed. It can be fully customized in the config.
• Referencing overseer.<module> no longer calls require("overseer.<module>")
  • There is no need for this magic and it makes it harder to understand the code.
• Template provider conditions can no longer define a callback function.
  • In practice these checks were often repeated in the generator function, so we can just remove it from the condition check.
• Removed template sort priority
  • With the removal of the generic template (e.g. make), I didn't see much use for this anymore.
• Removed configurable keymaps for task editor & form
  • Custom bindings are less necessary now, and can be added via filetype autocmds if necessary.
• Changed template_timeout -> template_timeout_ms
  • A minor config variable name refactor to make the units obvious
• Changed template_cache_threshold -> template_cache_threshold_ms
  • A minor config variable name refactor to make the units obvious
• Changed the resession extension config options
  • Previously they were passed in directly to overseer.list_tasks. This has been refactored to be more extensible.

Commands

Command	Diff
OverseerOpen[!]	No change
OverseerClose	No change
OverseerToggle[!]	No change
OverseerRun	No change
OverseerShell[!]	New command
OverseerTaskAction	No change
OverseerSaveBundle	Deleted - dropping the bundles feature
OverseerLoadBundle	Deleted - dropping the bundles feature
OverseerDeleteBundle	Deleted - dropping the bundles feature
OverseerRunCmd	Deleted - replaced by OverseerShell
OverseerInfo	Deleted - replaced by :checkhealth overseer
OverseerBuild	Deleted - extremely niche use case
OverseerQuickAction	Deleted - too confusingly similar to OverseerTaskAction
OverseerClearCache	Deleted - very rare to need to use this

API methods

API	Diff
overseer.setup	No change
overseer.on_setup	Deleted - the weird lazy loading has been removed, so this has no more use
overseer.new_task	No change
overseer.toggle	No change
overseer.open	No change
overseer.close	No change
overseer.list_task_bundles	Deleted - dropping the bundles feature
overseer.load_task_bundle	Deleted - dropping the bundles feature
overseer.save_task_bundle	Deleted - dropping the bundles feature
overseer.delete_task_bundle	Deleted - dropping the bundles feature
overseer.list_tasks	Changed the default sort order and the parameters
overseer.run_template	Renamed to run_task
overseer.preload_task_cache	No change
overseer.clear_task_cache	No change
overseer.run_action	No change
overseer.wrap_template	Deleted - this is no longer a recommended pattern for task templates
overseer.add_template_hook	No change
overseer.remove_template_hook	No change
overseer.register_template	No change
overseer.load_template	Deleted - template files are now automatically loaded
overseer.debug_parser	Deleted - the new parser system is simpler and doesn't need this debugger
overseer.register_alias	By default it will no longer overwrite an existing alias

Non-breaking changes

• Added checkhealth support
• fix all deprecation warnings in nvim 0.11
• on_output_summarize and display_duration are deprecated
  • these don't do anything anymore because task display is entirely controlled by the config.
• template generators can be sync
  • simple synchronous template generators should be easy to write, and now they are!
• auto-load templates
  • no need to create files that export a list of templates anymore or to manually specify which template files to load. Simply put your template files in the correct directory and overseer will automatically load them.
• task editor and params input form use inline virtual text
  • this makes them feel a little less janky to use.
• template generators can report errors
  • aids and debugging issues and is reported in checkhealth.
• wrap vim.system and vim.fn.jobstart
  • experimental mode that displays any call to vim.system or vim.fn.jobstart as an Overseer task.