diff options
Diffstat (limited to 'MAINTAIN.md')
| -rw-r--r-- | MAINTAIN.md | 123 |
1 files changed, 81 insertions, 42 deletions
diff --git a/MAINTAIN.md b/MAINTAIN.md index 9a8531fbd9..95a3916535 100644 --- a/MAINTAIN.md +++ b/MAINTAIN.md @@ -12,23 +12,23 @@ General guidelines * Use automation to solve problems * Never break the API... but sometimes break the UI -Ticket triage -------------- +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) +* 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 +* 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. +* 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 @@ -50,47 +50,86 @@ 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](https://github.com/neovim/neovim/blob/3d45706478cd030c3ee05b4f336164bb96138095/.github/workflows/release.yml#L11-L13) - will update the release assets based on the `stable` tag. + * Run `./scripts/release.sh` + * Update (force-push) the remote `stable` tag. + * The [CI job](https://github.com/neovim/neovim/blob/3d45706478cd030c3ee05b4f336164bb96138095/.github/workflows/release.yml#L11-L13) + will update the release assets and force-push to the `stable` tag. -The neovim repository includes a backport [github action](https://github.com/zeebe-io/backport-action). -In order to trigger the action, a PR must be labeled with a label matching the -form `backport release-0.X`. Note, the PR must have a description in the issue body, -or the backport will fail. +### Release automation + +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`. 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.lua`. + +* [LuaJIT](https://github.com/LuaJIT/LuaJIT) +* [Lua](https://www.lua.org/download.html) +* [Luv](https://github.com/luvit/luv) +* [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) + +### Vendored dependencies + +These dependencies are "vendored" (inlined), we must update the sources manually: + +* `src/mpack/`: [libmpack](https://github.com/libmpack/libmpack) + * 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) +* `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) + +### Forks + +We may maintain forks, if we are waiting on upstream changes: https://github.com/neovim/neovim/wiki/Deps + +CI -------------- -These "bundled" dependencies can be updated by bumping their versions in `cmake.deps/CMakeLists.txt`: - - [Lua](https://www.lua.org/download.html) - - [LuaJIT](https://github.com/LuaJIT/LuaJIT) - - [Luv](https://github.com/luvit/luv) - - [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) - - [tree-sitter](https://github.com/tree-sitter/tree-sitter) - -`scripts/bump-dep.sh` is a script that can automate this process for `LuaJIT`, `Luv`, `libuv` & `tree-sitter`. See usage guide: - - Run `./scripts/bump-deps.sh --dep Luv --version 1.43.0-0` to update a dependency. - See `./scripts/bump-deps.sh -h` for more detailed usage - - Run `./scripts/bump-deps.sh --pr` to create a pr - To generate the default PR title and body, the script uses the most recent commit (not in `master`) with prefix `build(deps): ` - -These dependencies are "vendored" (inlined), we need to update the sources manually: - - [libmpack](https://github.com/libmpack/libmpack) - - [xdiff](https://github.com/git/git/tree/master/xdiff) - - [lua-cjson](https://github.com/openresty/lua-cjson) - - [Klib](https://github.com/attractivechaos/klib) - - [inspect.lua](https://github.com/kikito/inspect.lua) - -We also maintain some forks, particularly for Windows, if we are waiting on upstream changes: -https://github.com/neovim/neovim/wiki/Deps +### 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. See also -------- -- https://github.com/neovim/neovim/issues/862 -- https://github.com/git/git/blob/master/Documentation/howto/maintain-git.txt +* https://github.com/neovim/neovim/issues/862 +* https://github.com/git/git/blob/master/Documentation/howto/maintain-git.txt |