Notes on maintaining the Neovim project.
- Decide by cost-benefit
- Write down what was decided
- Constraints are good
- Use automation to solve problems
- Never break the API... but sometimes break the UI
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:
- Next bugfix-release (1.0.x)
- Next feature-release (1.x.0)
The forecasting problem might be solved with an explicit priority system (like Bram's todo.txt). Meanwhile the Neovim priority system is defined by:
- PRs nearing completion.
- Issue labels. E.g. the
+plan
label increases the ticket's priority merely for having a plan written down: it is closer to completion than tickets without a plan. - Comment activity or new information.
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:
- Fix the bug on
master
. - Cherry-pick the fix to
release-x.y
. - Cut a release from
release-x.y
.- Run
./scripts/release.sh
- Update (force-push) the remote
stable
tag. - The CI job
will update the release assets and force-push to the
stable
tag.
- Run
Neovim automation includes a backport bot.
Trigger the action by labeling a PR with backport release-X.Y
. See .github/workflows/backport.yml
.
These "bundled" dependencies can be updated by bumping their versions in cmake.deps/CMakeLists.txt
.
Some can be auto-bumped by scripts/bump_deps.lua
.
- LuaJIT
- Lua
- Luv
- When bumping, also sync our bundled documentation with the upstream documentation.
- gettext
- libiconv
- libtermkey
- libuv
- libvterm
- lua-compat
- msys2 (for mingw Windows build)
- Changes to mingw can break our mingw build.
- tree-sitter
- unibilium
These dependencies are "vendored" (inlined), we must update the sources manually:
src/mpack/
: libmpack- send improvements upstream!
src/xdiff/
: xdiffsrc/cjson/
: lua-cjsonsrc/nvim/lib/
: Klibruntime/lua/vim/inspect.lua
: inspect.luasrc/nvim/tui/terminfo_defs.h
: terminfo definitions- Run
scripts/update_terminfo.sh
to update these definitions.
- Run
- treesitter parsers
We may maintain forks, if we are waiting on upstream changes: https://github.com/neovim/neovim/wiki/Deps
As our CI is primarily dependent on GitHub Actions at the moment, then so will our CI strategy be. The following guidelines have worked well for us so far:
- Never use a macOS runner if an Ubuntu or a Windows runner can be used instead. This is because macOS runners have a tighter restrictions on the number of concurrent jobs.
-
For special-purpose jobs where the runner version doesn't really matter, prefer
-latest
tags so we don't need to manually bump the versions. An example of a special-purpose workflow islabeler.yml
. -
For our testing jobs, which are in
test.yml
andbuild.yml
, prefer to use the latest stable (i.e. non-beta) 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 automatic bumping the CI versions will fail due to manual work being required from experience. -
For our release job, which is
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.