MAINTAIN.md
Notes on maintaining the Neovim project.
In practice we haven't found a way to forecast more precisely than "next" and "after next". So there are usually one or two (at most) planned milestones:
The forecasting problem might be solved with an explicit priority system (like Vim's todo.txt). Meanwhile the Neovim priority system is defined by:
has:plan label increases the ticket's priority merely
for having a plan written down: it is closer to completion than tickets
without a plan.Anything that isn't in the next milestone, and doesn't have a finished PR—is just not something you care very much about, by construction. Post-release you can review open issues, but chances are your next milestone is already getting full... :)
Release "often", but not "early".
The (unreleased) master branch is the "early" channel; it should not be
released if it's not stable. High-risk changes may be merged to master if
the next release is not imminent.
For maintenance releases, create a release-x.y branch. If the current release
has a major bug:
master.release-x.y.release-x.y.
./scripts/release.sh (requires git cliff)Neovim automation includes a backport bot.
Trigger the action by labeling a PR with ci:backport release-x.y. See .github/workflows/backport.yml.
Neovim inherits many features and design decisions from Vim, not all of which align with the goals of this project. It is sometimes desired or necessary to remove existing features, or refactor parts of the code that would change user's workflow. In these cases, a deprecation policy is needed to properly inform users of the change.
When a (non-experimental) feature is slated to be removed it should:
@deprecated).deprecated.txt.vim.deprecate(). The specified version is the
current minor version + 2. For example, if the current version is
v0.10.0-dev-1957+gd676746c33 then use 0.12.v:lua.vim.deprecate(). Use the same version
as described for Lua features.vim.deprecate(…, 'x.y.z') where major version x is greater than the
current Nvim major version, is always treated as soft deprecation.Example:
Deprecation Removal
┆ ┆ ┆
┆ Soft ┆ Hard ┆
┆ Deprecation ┆ Deprecation ┆
┆ Period ┆ Period ┆
────────────────────────────────────────────────────────────
Version: 0.10 0.11 0.12
────────────────────────────────────────────────────────────
Old code Old code Old code
+ +
New code New code New code
Feature removals which may benefit from community input or further discussion should also have a tracking issue (which should be linked to in the release notes).
Exceptions to this policy may be made (for experimental subsystems or when there is broad consensus among maintainers). The rationale for the exception should be stated explicitly and publicly.
(Note: keep this in sync with the "external" section of LICENSE.txt).
(TODO: declare deps in sbom.json, CycloneDX SBOM format).
"Bundled" dependencies can be updated by bumping their versions in cmake.deps/deps.txt.
Some can be auto-bumped by scripts/bump_deps.lua.
zig fetch --save git+https://github.com/allyourcodebase/libuv.git#<refname> manually.master branch."Vendored" (inlined) dependencies are part of the repo tree and we must update the sources manually:
src/mpack/: libmpack
src/mpack/lmpack.c: libmpack-lua
src/xdiff/: xdiffsrc/cjson/: lua-cjsonsrc/klib/: Klibruntime/lua/vim/inspect.lua: inspect.luasrc/nvim/tui/terminfo_defs.h: terminfo definitions
scripts/update_terminfo.sh to update these definitions.runtime/lua/vim/lsp/_meta/protocol.lua: LSP specification
src/gen/gen_lsp.lua to update.runtime/lua/vim/_meta/lpeg.lua: LPeg definitions.
LuaCATS/lpeg for updates.runtime/lua/vim/re.lua: LPeg regex module.
runtime/lua/vim/_meta/re.lua: docs for LPeg regex module.
src/bit.c: only for PUC lua: port of require'bit' from luajit https://bitop.luajit.org/runtime/lua/coxpcall.lua: coxpcall (only needed for PUC lua, builtin to luajit)CODECOV_TOKENBACKPORT_KEYBACKPORT_APPRefactoring Vim structurally and aesthetically is an important goal of Neovim. But there are some modules that should not be changed significantly, because they are maintained by Vim, at present. Until someone takes "ownership" of these modules, the cost of any significant changes (including style or structural changes that re-arrange the code) to these modules outweighs the benefit. The modules are:
regexp.cindent_c.cDiscussions from issues and PRs are backed up here: https://github.com/neovim/neovim-backup
-latest tags so we don't need to manually bump the versions. An
example of a special-purpose workflow is labeler_pr.yml.test.yml, prefer to use the latest version
explicitly. Avoid using the -latest tags here as it makes it difficult
to determine from an unrelated PR if a failure is due to the PR itself or
due to GitHub bumping the -latest tag without our knowledge. There's
also a high risk that automatically bumping the CI versions will fail due
to manual work being required from experience.release.yml, prefer to use the oldest
stable (i.e. non-deprecated) versions available. The reason is that we're
trying to produce images that work in the broadest number of environments,
and therefore want to use older releases.Some github labels are used to trigger certain jobs:
ci:backport release-x.y - backport to branch release-x.yci:s390x - enable s390x CIci:skip-news - skip news.yml workflowsci:windows-asan - test windows with ASAN enabledneeds:response - close PR after a certain amount of time if author doesn't
respondMultiple Vim versions are tracked in version.c, so that has('patch-x.y.z')
works even if v:version is "behind". Whenever we "complete" merging all
patches from a Vim v:version, the steps to bump v:version are:
vim-patch.sh by adjusting the regexp.
For example, to remove version "8.1":
diff --git a/scripts/vim-patch.sh b/scripts/vim-patch.sh
index d64f6b6..1d3dcdf 100755
--- a/scripts/vim-patch.sh
+++ b/scripts/vim-patch.sh
@@ -577,7 +577,7 @@ list_vimpatch_tokens() {
# Left-pad the patch number of "vim-patch:xxx" for stable sort + dedupe.
# Filter reverted Vim tokens.
list_vimpatch_numbers() {
- local patch_pat='(8\.[12]|9\.[0-9])\.[0-9]{1,4}'
+ local patch_pat='(8\.[2]|9\.[0-9])\.[0-9]{1,4}'
diff "${NVIM_SOURCE_DIR}/scripts/vimpatch_token_reverts.txt" <(
git -C "${NVIM_SOURCE_DIR}" log --format="%s%n%b" -E --grep="^[* ]*vim-patch:${patch_pat}" |
grep -oE "^[* ]*vim-patch:${patch_pat}" |
nvim -l scripts/vimpatch.lua to regenerate version.c. Or wait for the
vim_patches.yml CI job to do it.