Prepare for 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
   • Lua stdlib deprecation strategy; "frozen" phase #31376

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.

[ilan-schemoul]

I hope I am not adding noise but I believe transparency in project management may be valuable for the community. If it's not the right place to ask or not my place to ask I'd understand and apologize.

My question is about how much of a priority are the issues linked there ?

Because from a user perspective (2 years very happy user with a heavy 70+ plugins config and occasional contributors of plugins) neovim seems already extremely stable, very capable and with an outsanding plugin ecosystem. The 0.X versionning can hurt the project by slowing down adoption (I really hesitated making the switch to nvim and many people I know do because of version. 0.X can scream unstable, buggy software to some). There is an very strong network effect for code editors with plugins (73% of devs use VSCode in 2023 (stackoverflow survey) so plugins are made for VScode; and because of plugins more users use VSCode etc.) therefore every day without 1.X has compounding effects beyond just the immediately lost users. And it's in everyone's interest to have a network effect in our favor because plugins are a game changer.

And 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. I understand some people might feel different and 100% respect that but believe transparency about certain decisions might be helpful.

Thanks for all your efforts for this outsanding editor

[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.