Skip to content

Latest commit

 

History

History
135 lines (101 loc) · 5.43 KB

MAINTAIN.md

File metadata and controls

135 lines (101 loc) · 5.43 KB
Raw

Maintaining the Neovim project

Notes on maintaining the Neovim project.

General guidelines

  • 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

Issue triage

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 policy

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:

  1. Fix the bug on master.
  2. Cherry-pick the fix to release-x.y.
  3. 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.

Release automation

Neovim automation includes a backport bot. Trigger the action by labeling a PR with backport release-X.Y. See .github/workflows/backport.yml.

Third-party dependencies

These "bundled" dependencies can be updated by bumping their versions in cmake.deps/CMakeLists.txt. Some can be auto-bumped by scripts/bump-deps.sh.

Vendored dependencies

These dependencies are "vendored" (inlined), we must update the sources manually:

  • src/mpack/: libmpack
    • send improvements upstream!
  • src/xdiff/: xdiff
  • src/cjson/: lua-cjson
  • src/nvim/lib/: Klib
  • runtime/lua/vim/inspect.lua: inspect.lua
  • src/nvim/tui/terminfo_defs.h: terminfo definitions
    • Run scripts/update_terminfo.sh to update these definitions.
  • treesitter parsers

Forks

We may maintain forks, if we are waiting on upstream changes: https://github.com/neovim/neovim/wiki/Deps

CI

General

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:

Runner versions

  • 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 is labeler.yml.

  • For our testing jobs, which is currently only ci.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.

See also