diff options
Diffstat (limited to 'MAINTAIN.md')
| -rw-r--r-- | MAINTAIN.md | 141 |
1 files changed, 106 insertions, 35 deletions
diff --git a/MAINTAIN.md b/MAINTAIN.md index 95a3916535..ff5f3fe5a1 100644 --- a/MAINTAIN.md +++ b/MAINTAIN.md @@ -25,7 +25,7 @@ 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 +* 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. @@ -60,25 +60,75 @@ has a major bug: Neovim automation includes a [backport bot](https://github.com/zeebe-io/backport-action). Trigger the action by labeling a PR with `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`) only. + - Include a note in `news.txt` under `DEPRECATIONS`. +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 + (typically via `vim.deprecate()` for Lua features). + - Features implemented in Vimscript or 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: + +``` + Deprecation Removal + ┆ ┆ ┆ + ┆ Soft ┆ Hard ┆ + ┆ Deprecation ┆ Deprecation ┆ + ┆ Period ┆ Preiod ┆ + ──────────────────────────────────────────────────────────── +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 ------------------------ -These "bundled" dependencies can be updated by bumping their versions in `cmake.deps/CMakeLists.txt`. +These "bundled" dependencies can be updated by bumping their versions in `cmake.deps/deps.txt`. Some can be auto-bumped by `scripts/bump_deps.lua`. * [LuaJIT](https://github.com/LuaJIT/LuaJIT) * [Lua](https://www.lua.org/download.html) * [Luv](https://github.com/luvit/luv) + * When bumping, also sync [our bundled documentation](https://github.com/neovim/neovim/blob/master/runtime/doc/luvref.txt) with [the upstream documentation](https://github.com/luvit/luv/blob/master/docs.md). * [gettext](https://ftp.gnu.org/pub/gnu/gettext/) * [libiconv](https://ftp.gnu.org/pub/gnu/libiconv) * [libtermkey](https://github.com/neovim/libtermkey) * [libuv](https://github.com/libuv/libuv) * [libvterm](http://www.leonerd.org.uk/code/libvterm/) * [lua-compat](https://github.com/keplerproject/lua-compat-5.3) -* [msys2](https://github.com/msys2/MINGW-packages) (for mingw Windows build) - * Changes to mingw can [break our mingw build](https://github.com/msys2/MINGW-packages/issues/9946). * [tree-sitter](https://github.com/tree-sitter/tree-sitter) * [unibilium](https://github.com/neovim/unibilium) +* [treesitter parsers](https://github.com/neovim/neovim/blob/7e97c773e3ba78fcddbb2a0b9b0d572c8210c83e/cmake.deps/deps.txt#L47-L62) ### Vendored dependencies @@ -88,45 +138,66 @@ These dependencies are "vendored" (inlined), we must update the sources manually * send improvements upstream! * `src/xdiff/`: [xdiff](https://github.com/git/git/tree/master/xdiff) * `src/cjson/`: [lua-cjson](https://github.com/openresty/lua-cjson) -* `src/nvim/lib/`: [Klib](https://github.com/attractivechaos/klib) +* `src/klib/`: [Klib](https://github.com/attractivechaos/klib) * `runtime/lua/vim/inspect.lua`: [inspect.lua](https://github.com/kikito/inspect.lua) * `src/nvim/tui/terminfo_defs.h`: terminfo definitions * Run `scripts/update_terminfo.sh` to update these definitions. -* [treesitter parsers](https://github.com/neovim/neovim/blob/fcc24e43e0b5f9d801a01ff2b8f78ce8c16dd551/cmake.deps/CMakeLists.txt#L197-L210) +* `runtime/lua/vim/lsp/_meta/protocol.lua`: LSP specification + * Run `scripts/gen_lsp.lua` to update. +* `runtime/lua/vim/_meta/lpeg.lua`: LPeg definitions. + * Refer to [`LuaCATS/lpeg`](https://github.com/LuaCATS/lpeg) for updates. +* `runtime/lua/vim/re.lua`: LPeg regex module. + * Vendored from LPeg. Needs to be updated when LPeg is updated. +* `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) ### 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: - -* 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](https://docs.github.com/en/actions/learn-github-actions/usage-limits-billing-and-administration#usage-limits). - -### 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. +Non-technical dependencies +-------------------------- + +* GitHub users: + * https://github.com/marvim + * https://github.com/nvim-winget +* Domain names (held in https://namecheap.com): + * neovim.org + * neovim.io + * packspec.org + * pkgjson.org +* DNS for the above domains is managed in https://cloudflare.com (not the domain registrar) + +Automation (CI) +--------------- + +### Backup + +Discussions from issues and PRs are backed up here: +https://github.com/neovim/neovim-backup + +### Development guidelines + +* CI and automation jobs are primarily driven by GitHub Actions. +* Avoid macOS if an Ubuntu or a Windows runner can be used instead. This is + 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). + +* 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 are in `test.yml` and `build.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 + 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. See also -------- |