Path to version 1.0

[justinmk]

This post lists the conditions for declaring Nvim v1.0. This is not a roadmap; the project roadmap is here: https://neovim.io/roadmap/

What is the plan for 1.0?

Stick to 0.x until the following conditions:

1. we have a full picture of what the RPC API and Lua APIs look like, this means conventions for:
   • function signatures (all RPC functions should have opts param and return a Dict to ensure ability to augment them without breaking back-compat)
   • naming conventions, :help dev-api :help dev-lua
   • Lua: plugins can easily get Lua annotations metadata #22287
   • Lua: structured concurrency, Promises, task pipelines #19624
   • Lua: iterable stdlib #18585
   • Lua stdlib: guidelines for raising errors #11311
   • vimscript introspection / meta structure #19918
2. Remove vim.opt/vim.opt_local/vim.opt_global
3. Redesign the "remote plugin" concept: simplify remote plugins, massively #27949
4. Redesign --remote docs: --remote alternatives #18414
5. :checkhealth reports use of deprecated RPC and Lua APIs.
6. :lua foo.<tab> completion should not suggest deprecated things. Lua: cmdline "vim.<tab>" completion: skip private and deprecated things #21660

1.0

Release 1.0 when we have fully-specified conventions for RPC API and Lua stdlib.

• During 0.x, and continuing through 1.x, we will aggressively deprecate interfaces. This means:
  1. they will be listed in :help deprecated, and
  2. where possible they will be flagged by vim.deprecate().
• No APIs will be removed from the RPC API during 1.x.
• Deprecated RPC APIs emit warnings in some visible place when used.

2.0

• REMOVE all deprecated things in the 2.0 release. See also :help api-contract.
• Create nvim_xx functions that alias all nvim_xx2 functions.
  • Deprecate the existing nvim_xx2 names.
  • Example: nvim_exec will alias nvim_exec2. nvim_exec2 will still exist but will be deprecated, and clients using nvim_exec2 can easily migrate to nvim_exec.

[clason]

I think we're doing just fine as-is. The versioning is driven by a very strong API contract (:h api-contract), and that (likely) won't change. If you want to ask questions and discuss things, feel free to reach out on Matrix; comments like this on an issue tracker do add noise.

[justinmk]

The 0.X versionning can hurt the project by slowing down adoption

That's ok, and also somewhat intentional. Because the things blocking 1.0 are things that must be fixed before we gain those remaining users who pay attention to the "1.0" signal.

neovim seems already extremely stable

That's not the standard for 1.0. What's needed for 1.0 is to decide various "one-way doors".

for example having guidelines to raise errors or a native Promise system (when plenary does an ok job) don't seem required for a 1.0.

Promise/task is perhaps negotiable, but that doesn't really matter until the rest of the list is mostly complete.