neovim

Neovim text editor
git clone https://git.dasho.dev/neovim.git
Log | Files | Refs | README

MAINTAIN.md (12719B)

Maintaining the Neovim project ==============================

Notes on maintaining the Neovim project.

General guidelines

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:

The forecasting problem might be solved with an explicit priority system (like Vim's todo.txt). Meanwhile the Neovim priority system is defined by:

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 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. Comment activity or new information.
  2. Comment activity or new information.
  3. Comment activity or new information.

* Run ./scripts/release.sh (requires git cliff) * 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 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. Comment activity or new information.

- 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. - vim.deprecate(…, 'x.y.z') where major version x is greater than the current Nvim major version, is always treated as soft deprecation.

  1. Comment activity or new information.

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

  1. Comment activity or new information.

- 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:

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.

Third-party dependencies

"Bundled" dependencies can be updated by bumping their versions in cmake.deps/deps.txt. Some can be auto-bumped by scripts/bump_deps.lua.

* Requires a PR to update the Zig package first. If the script fails, run zig fetch --save git+https://github.com/allyourcodebase/libuv.git#<refname> manually.

* When bumping, also sync - our bundled meta file with the upstream meta file; - our bundled documentation with the upstream documentation.

* The original project was abandoned, so the neovim/unibilium fork is considered "upstream" and is maintained on the master branch. * Note: unibilium is NOT required. See BUILD.md to build Nvim without unibilium.

Vendored dependencies

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

* send improvements upstream!

* send improvements upstream!

* Run scripts/update_terminfo.sh to update these definitions.

* Run src/gen/gen_lsp.lua to update.

* Refer to `LuaCATS/lpeg` for updates. * Update the git SHA revision from which the documentation was taken.

* Vendored from LPeg. Needs to be updated when LPeg is updated.

* Needs to be updated when LPeg is updated.

Other dependencies

* https://github.com/marvim * https://github.com/nvim-winget

* CODECOV_TOKEN * BACKPORT_KEY

* BACKPORT_APP

* neovim.org * neovim.io * packspec.org * pkgjson.org

Refactoring

Frozen legacy modules

Refactoring 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:

Automation (CI)

Backup

Discussions from issues and PRs are backed up here: https://github.com/neovim/neovim-backup

Development guidelines

because macOS runners have [tighter restrictions on the number of concurrent jobs](https://docs.github.com/en/actions/learn-github-actions/usage-limits-billing-and-administration#usage-limits).

* 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_pr.yml. * For our testing job 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. * 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.

Special labels

Some github labels are used to trigger certain jobs:

respond

Vim patches

Multiple 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:

  1. needs:response - close PR after a certain amount of time if author doesn't

For example, to remove version "8.1": `diff 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 @@ listvimpatchtokens() { # Left-pad the patch number of "vim-patch:xxx" for stable sort + dedupe. # Filter reverted Vim tokens. listvimpatchnumbers() { - 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 "${NVIMSOURCEDIR}/scripts/vimpatchtokenreverts.txt" <( git -C "${NVIMSOURCEDIR}" log --format="%s%n%b" -E --grep="^[* ]*vim-patch:${patch_pat}" | grep -oE "^[* ]*vim-patch:${patch_pat}" | `

  1. needs:response - close PR after a certain amount of time if author doesn't

vim_patches.yml CI job to do it.

See also