neovim/CONTRIBUTING.md

Contributing to Neovim

Getting started

If you want to help but don't know where to start, here are some low-risk/isolated tasks:

• Try a complexity:low issue.
• Fix bugs found by Clang, PVS or Coverity.
• Improve documentation
• Merge a Vim patch (requires strong familiarity with Vim)
  • NOTE: read the above link before sending improvements to "runtime files" (anything in runtime/).
    • Vimscript and documentation files are (mostly) maintained by Vim, not Nvim.
    • Lua files are maintained by Nvim.

Reporting problems

• Check the FAQ.
• Search existing issues (including closed!)
• Update Neovim to the latest version to see if your problem persists.
• Try to reproduce with nvim --clean ("factory defaults").
• Bisect your config: disable plugins incrementally, to narrow down the cause of the issue.
• Bisect Neovim's source code to find the cause of a regression, if you can. This is extremely helpful.
• When reporting a crash, include a stacktrace.
• Use ASAN/UBSAN to get detailed errors for segfaults and undefined behavior.
• Check the logs. :edit $NVIM_LOG_FILE
• Include cmake --system-information for build-related issues.

Developer guidelines

• Read :help dev if you are working on Nvim core.
• Read :help dev-ui if you are developing a UI.
• Read :help dev-api-client if you are developing an API client.
• Install ninja for faster builds of Nvim.

  sudo apt-get install ninja-build
  make distclean
  make  # Nvim build system uses ninja automatically, if available.
  

Pull requests (PRs)

• To avoid duplicate work, create a draft pull request.
• Your PR must include test coverage.
• Avoid cosmetic changes to unrelated files in the same commit.
• Use a feature branch instead of the master branch.
• Use a rebase workflow for small PRs.
  • After addressing review comments, it's fine to force-push.
• Use a merge workflow (as opposed to "rebase") for big, high-risk PRs.
  • Merge master into your PR when there are conflicts or when master introduces breaking changes.
  • Do not edit commits that come before the merge commit.

Merging to master

For maintainers: when a PR is ready to merge to master,

• prefer Squash Merge for "single-commit PRs" (when the PR has only one meaningful commit).
• prefer Merge for "multi-commit PRs" (when the PR has multiple meaningful commits).

Stages: Draft and Ready for review

Pull requests have two stages: Draft and Ready for review.

1. Create a Draft PR while you are not requesting feedback as you are still working on the PR.
   • You can skip this if your PR is ready for review.
2. Change your PR to ready when the PR is ready for review.
   • You can convert back to Draft at any time.

Do not add labels like [RFC] or [WIP] in the title to indicate the state of your PR: this just adds noise. Non-Draft PRs are assumed to be open for comments; if you want feedback from specific people, @-mention them in a comment.

Commit messages

Follow the conventional commits guidelines to make reviews easier and to make the VCS/git logs more valuable. The general structure of a commit message is:

<type>([optional scope]): <description>

[optional body]

[optional footer(s)]

• Prefix the commit subject with one of these types:
  • build, ci, docs, feat, fix, perf, refactor, revert, test, vim-patch, dist
  • You can ignore this for "fixup" commits or any commits you expect to be squashed.
• Append optional scope to type such as (lsp), (treesitter), (float), …
• Description shouldn't start with a capital letter or end in a period.
• Use the imperative voice: "Fix bug" rather than "Fixed bug" or "Fixes bug."
• Try to keep the first line under 72 characters.
• A blank line must follow the subject.
• Breaking API changes must be indicated by
  1. "!" after the type/scope, and
  2. a "BREAKING CHANGE" footer describing the change. Example:

     refactor(provider)!: drop support for Python 2
     
     BREAKING CHANGE: refactor to use Python 3 features since Python 2 is no longer supported.
     

Automated builds (CI)

Each pull request must pass the automated builds on Cirrus CI and GitHub Actions.

• CI builds are compiled with -Werror, so compiler warnings will fail the build.
• If any tests fail, the build will fail. See test/README.md#running-tests to run tests locally. Passing locally doesn't guarantee passing the CI build, because of the different compilers and platforms tested against.
• CI runs ASan and other analyzers.
  • To run valgrind locally: VALGRIND=1 make test
  • To run Clang ASan/UBSan locally: CC=clang make CMAKE_FLAGS="-DCLANG_ASAN_UBSAN=ON"
• The lint build checks modified lines and their immediate neighbors, to encourage incrementally updating the legacy style to meet our style. (See #3174 for background.)
• CI for FreeBSD runs on Cirrus CI.

Clang scan-build

View the Clang report to see potential bugs found by the Clang scan-build analyzer.

• Search the Neovim commit history to find examples:

  git log --oneline --no-merges --grep clang
  

• To verify a fix locally, run scan-build like this:

  rm -rf build/
  scan-build --use-analyzer=/usr/bin/clang make
  

PVS-Studio

View the PVS report to see potential bugs found by PVS Studio.

• Use this format for commit messages (where {id} is the PVS warning-id)):

  fix(PVS/V{id}): {description}
  

• Search the Neovim commit history to find examples:

  git log --oneline --no-merges --grep PVS
  

• Try ./scripts/pvscheck.sh to run PVS locally.

Coverity

Coverity runs against the master build. To view the defects, just request access; you will be approved.

• Use this format for commit messages (where {id} is the CID (Coverity ID); (example)):

  fix(coverity/{id}): {description}
  

• Search the Neovim commit history to find examples:

  git log --oneline --no-merges --grep coverity
  

Clang sanitizers (ASAN and UBSAN)

ASAN/UBSAN can be used to detect memory errors and other common forms of undefined behavior at runtime in debug builds.

• To build Neovim with sanitizers enabled, use

  rm -rf build && CMAKE_EXTRA_FLAGS="-DCMAKE_C_COMPILER=clang -DCLANG_ASAN_UBSAN=1" make
  

• When running Neovim, use

  UBSAN_OPTIONS=print_stacktrace=1 ASAN_OPTIONS=log_path=/tmp/nvim_asan nvim args...
  

• If Neovim exits unexpectedly, check /tmp/nvim_asan.{PID} (or your preferred log_path) for log files with error messages.

Coding

Lint

You can run the linter locally by:

make lint

The lint step downloads the master error list and excludes them, so only lint errors related to the local changes are reported.

You can lint a single file (but this will not exclude legacy errors):

./src/clint.py src/nvim/ops.c

Style

• You can format files by using:

    make format
  

  This will format changed Lua and C files with all appropriate flags set.
• Style rules are (mostly) defined by src/uncrustify.cfg which tries to match the style-guide. To use the Nvim gq command with uncrustify:

  if !empty(findfile('src/uncrustify.cfg', ';'))
    setlocal formatprg=uncrustify\ -q\ -l\ C\ -c\ src/uncrustify.cfg\ --no-backup
  endif
  

  The required version of uncrustify is specified in uncrustify.cfg.
• There is also .clang-format which has drifted from the style-guide, but is available for reference. To use the Nvim gq command with clang-format:

  if !empty(findfile('.clang-format', ';'))
    setlocal formatprg=clang-format\ -style=file
  endif
  

Navigate

• Set blame.ignoreRevsFile to ignore noise commits in git blame:

  git config blame.ignoreRevsFile .git-blame-ignore-revs
  

• Recommendation is to use clangd. Can use the maintained config in nvim-lspconfig/clangd.

• Explore the source code on the web.

• If using lua-language-server, symlink contrib/luarc.json into the project root:

  $ ln -s contrib/luarc.json .luarc.json
  

Includes

For managing includes in C files, use include-what-you-use.

• Install include-what-you-use
• Run with:

  make CMAKE_EXTRA_FLAGS=-DCMAKE_C_INCLUDE_WHAT_YOU_USE=include-what-you-use | tee iwyu.txt
  

See #549 for more details.

Documenting

Many parts of the :help documentation are autogenerated from C or Lua docstrings using the ./scripts/gen_vimdoc.py script. You can filter the regeneration based on the target (api, lua, or lsp), or the file you changed, that need a doc refresh using ./scripts/gen_vimdoc.py -t <target>.

Lua docstrings

Lua documentation uses a subset of EmmyLua annotations. A rough outline of a function documentation is

--- {Brief}
---
--- {Long explanation}
---
---@param arg1 type {description}
---@param arg2 type {description}
{...}
---
---@return type {description}

If possible, always add type information (table, string, number, ...). Multiple valid types are separated by a bar (string|table). Indicate optional parameters via type|nil.

If a function in your Lua module should not be documented (e.g. internal function or local function), you should set the doc comment to:

---@private

Mark functions that are deprecated as

---@deprecated

Reviewing

To help review pull requests, start with this checklist.

Reviewing can be done on GitHub, but you may find it easier to do locally. Using GitHub CLI, you can create a new branch with the contents of a pull request, e.g. #1820:

gh pr checkout https://github.com/neovim/neovim/pull/1820

Use git log -p master..FETCH_HEAD to list all commits in the feature branch which aren't in the master branch; -p shows each commit's diff. To show the whole surrounding function of a change as context, use the -W argument as well.