neovim/MAINTAIN.md
dundargoc 08991b0782
docs: small fixes
Co-authored-by: Christian Clason <c.clason@uni-graz.at>
Co-authored-by: Gregory Anders <greg@gpanders.com>
Co-authored-by: HiPhish <hiphish@posteo.de>
Co-authored-by: Julio B <julio.bacel@gmail.com>
Co-authored-by: T727 <74924917+T-727@users.noreply.github.com>
Co-authored-by: camoz <camoz@users.noreply.github.com>
Co-authored-by: champignoom <66909116+champignoom@users.noreply.github.com>
2023-05-13 21:33:22 +02:00

139 lines
5.7 KiB
Markdown

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 `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`.
* 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.
### 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)
* 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)
### 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/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.
* `src/bit.c`: only for PUC lua: port of `require'bit'` from luajit https://bitop.luajit.org/
* [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
--------------
### 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 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 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