Skip to content

Latest commit

 

History

History
240 lines (192 loc) · 10.9 KB

MAINTAIN.md

File metadata and controls

240 lines (192 loc) · 10.9 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 Vim's todo.txt). Meanwhile the Neovim priority system is defined by:

  • PRs nearing completion.
  • Issue labels. E.g. the 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.
  • 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.

Release automation

Neovim automation includes a backport bot. Trigger the action by labeling a PR with ci:backport release-x.y. See .github/workflows/backport.yml.

Deprecating and removing features

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:

  1. Be soft deprecated in the next release
    • Use of the deprecated feature will still work.
    • This means deprecating via documentation and annotation (@deprecated).
    • Include a note in deprecated.txt.
    • For Lua features, use 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.
    • For Vimscript features, use v:lua.vim.deprecate(). Use the same version as described for Lua features.
  2. Be hard deprecated in a following a release in which it was soft deprecated.
    • Use of the deprecated feature will still work but should issue a warning.
    • Features implemented in C will need bespoke implementations to communicate to users that the feature is deprecated.
  3. Be removed in a release following the release in which it was hard deprecated
    • Usually this will be the next release, but it may be a later release if a longer deprecation cycle is desired
    • If possible, keep the feature as a stub (e.g. function API) and issue an error when it is accessed.

Example: