2019-07-19 12:32:04 -07:00
Contributing to Neovim
======================
2014-02-24 16:32:15 -07:00
2016-08-09 21:47:04 -07:00
Getting started
---------------
2014-02-24 16:32:15 -07:00
2016-08-09 21:47:04 -07:00
If you want to help but don't know where to start, here are some
low-risk/isolated tasks:
2015-03-09 16:20:15 -07:00
2017-06-06 06:02:51 -07:00
- [Merge a Vim patch].
2020-01-29 04:06:35 -07:00
- Try a [good first issue ](../../labels/good%20first%20issue ) or [complexity:low] issue.
2019-01-08 11:58:06 -07:00
- Fix bugs found by [Clang ](#clang-scan-build ), [PVS ](#pvs-studio ) or
[Coverity ](#coverity ).
2017-04-17 14:52:38 -07:00
2019-07-19 12:32:04 -07:00
Reporting problems
------------------
- [Check the FAQ][wiki-faq].
- [Search existing issues][github-issues] (including closed!)
- Update Neovim to the latest version to see if your problem persists.
- Disable plugins incrementally, to narrow down the cause of the issue.
- When reporting a crash, [include a stacktrace ](https://github.com/neovim/neovim/wiki/FAQ#backtrace-linux ).
- [Bisect][git-bisect] to the cause of a regression, if you are able. This is _extremely_ helpful.
- Check `$NVIM_LOG_FILE` , if it exists.
- Include `cmake --system-information` for build-related issues.
2017-04-17 14:52:38 -07:00
Developer guidelines
--------------------
2019-01-08 11:58:06 -07:00
- Nvim contributors should read `:help dev` .
2017-04-17 14:52:38 -07:00
- External UI developers should read `:help dev-ui` .
2017-12-27 11:30:23 -07:00
- API client developers should read `:help dev-api-client` .
- Nvim developers are _strongly encouraged_ to install `ninja` for faster builds.
```
sudo apt-get install ninja-build
make distclean
make # Nvim build system uses ninja automatically, if available.
```
2021-01-27 13:15:52 -07:00
- [Improve documentation][wiki-contribute-help]
2016-08-09 21:47:04 -07:00
2019-01-10 17:20:15 -07:00
Pull requests (PRs)
2016-08-09 21:47:04 -07:00
---------------------
2016-06-03 12:05:44 -07:00
2017-04-17 14:52:38 -07:00
- To avoid duplicate work, create a `[WIP]` pull request as soon as possible.
2019-01-10 17:20:15 -07:00
- Your PR must include **test coverage.** See [test/README.md][run-tests].
2017-06-06 06:02:51 -07:00
- Avoid cosmetic changes to unrelated files in the same commit.
2016-06-03 12:05:44 -07:00
- Use a [feature branch][git-feature-branch] instead of the master branch.
2017-04-17 14:52:38 -07:00
- Use a **rebase workflow** for small PRs.
- After addressing review comments, it's fine to rebase and force-push.
- Use a **merge workflow** for big, high-risk PRs.
- Merge `master` into your PR when there are conflicts or when master
introduces breaking changes.
- Use the `ri` git alias:
```
[alias]
2017-05-08 11:28:41 -07:00
ri = "!sh -c 't=\"${1:-master}\"; s=\"${2:-HEAD}\"; mb=\"$(git merge-base \"$t\" \"$s\")\"; if test \"x$mb\" = x ; then o=\"$t\"; else lm=\"$(git log -n1 --merges \"$t..$s\" --pretty=%H)\"; if test \"x$lm\" = x ; then o=\"$mb\"; else o=\"$lm\"; fi; fi; test $# -gt 0 && shift; test $# -gt 0 && shift; git rebase --interactive \"$o\" \"$@\"'"
2017-04-17 14:52:38 -07:00
```
2017-04-06 15:31:39 -07:00
This avoids unnecessary rebases yet still allows you to combine related
commits, separate monolithic commits, etc.
2017-04-17 14:52:38 -07:00
- Do not edit commits that come before the merge commit.
- During a squash/fixup, use `exec make -C build unittest` between each
pick/edit/reword.
2015-04-21 14:35:06 -07:00
2016-08-23 20:49:09 -07:00
### Stages: WIP, RFC, RDY
2015-04-21 14:35:06 -07:00
2016-08-23 20:49:09 -07:00
Pull requests have three stages: `[WIP]` (Work In Progress), `[RFC]` (Request
For Comment) and `[RDY]` (Ready).
2015-03-09 16:20:15 -07:00
2020-01-13 00:41:55 -07:00
1. `[RFC]` is assumed by default, **do not** put "RFC" in the PR title (it adds
noise to merge commit messages).
2. Add `[WIP]` to the PR title if you are _not_ requesting feedback and the work
is still in flux.
3. Add `[RDY]` to the PR title if you are _done_ and only waiting on merge.
2015-03-09 16:20:15 -07:00
2016-06-03 12:05:44 -07:00
### Commit messages
2015-03-09 16:20:15 -07:00
2021-06-10 10:08:58 -07:00
Follow the [convential commits guidelines][conventional_commits] to *make reviews easier* and to make
the VCS/git logs more valuable. The general structure of a commit message is as follows:
2015-03-09 16:20:15 -07:00
2021-06-10 10:08:58 -07:00
```
< type > ([optional scope]): < description >
[optional body]
[optional footer(s)]
```
- **Prefix the commit subject with a _type_ :** `doc:` , `test:`
2016-06-03 12:05:44 -07:00
`runtime:` , ...
2019-01-08 11:58:06 -07:00
- Subject line for commits with only style/lint changes can be a single
word: `style` or `lint` .
2021-06-10 10:08:58 -07:00
- **Add the optional scope following < type > if possible:** `(lsp)` , `(treesitter)` , `(multigrid)` , ...
- Try to keep the first line under 72 characters.
2016-06-03 12:05:44 -07:00
- A blank line must separate the subject from the description.
2021-06-10 10:08:58 -07:00
- Breaking changes must be indicated at the very beginning of the footer or body section of a commit. A breaking change must consist of the uppercase text BREAKING CHANGE, followed by a colon, a space, and a description of what has changed about the API.
- Check your commit message for spelling and grammatical mistakes.
2016-06-03 12:05:44 -07:00
- Use the _imperative voice_ : "Fix bug" rather than "Fixed bug" or "Fixes bug."
2015-03-09 16:20:15 -07:00
2016-06-03 12:05:44 -07:00
### Automated builds (CI)
2015-03-09 16:20:15 -07:00
2019-10-19 18:04:08 -07:00
Each pull request must pass the automated builds on [Travis CI], [sourcehut]
2017-06-06 06:02:51 -07:00
and [AppVeyor].
2015-03-09 16:20:15 -07:00
2017-06-06 06:02:51 -07:00
- CI builds are compiled with [`-Werror`][gcc-warnings], so compiler warnings
will fail the build.
2016-06-03 12:05:44 -07:00
- If any tests fail, the build will fail.
2017-11-14 02:47:49 -07:00
See [test/README.md#running-tests][run-tests] to run tests locally.
2016-06-03 12:05:44 -07:00
Passing locally doesn't guarantee passing the CI build, because of the
different compilers and platforms tested against.
2017-07-29 09:51:31 -07:00
- 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"`
2019-07-19 12:32:04 -07:00
- The [lint ](#lint ) build checks modified lines _and their immediate
neighbors_, to encourage incrementally updating the legacy style to meet our
[style ](#style ). (See [#3174][3174] for background.)
2019-10-19 18:04:08 -07:00
- CI for freebsd and openbsd runs on [sourcehut].
- To get a backtrace on freebsd (after connecting via ssh):
```sh
sudo pkg install tmux # If you want tmux.
lldb build/bin/nvim -c nvim.core
# To get a full backtrace:
# 1. Rebuild with debug info.
rm -rf nvim.core build
2020-11-12 11:20:00 -07:00
gmake CMAKE_BUILD_TYPE=RelWithDebInfo CMAKE_EXTRA_FLAGS="-DCI_BUILD=ON -DMIN_LOG_LEVEL=3" nvim
2019-10-19 18:04:08 -07:00
# 2. Run the failing test to generate a new core file.
TEST_FILE=test/functional/foo.lua gmake functionaltest
lldb build/bin/nvim -c nvim.core
2019-07-19 12:32:04 -07:00
```
2017-01-31 00:53:16 -07:00
2017-06-05 18:43:53 -07:00
### Clang scan-build
2019-01-08 11:58:06 -07:00
View the [Clang report] to see potential bugs found by the Clang
[scan-build ](https://clang-analyzer.llvm.org/scan-build.html ) analyzer.
2017-06-05 18:43:53 -07:00
2019-01-08 11:58:06 -07:00
- 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
```
2015-03-09 16:20:15 -07:00
2019-01-08 11:58:06 -07:00
### PVS-Studio
2015-03-09 16:20:15 -07:00
2019-01-08 11:58:06 -07:00
View the [PVS report ](https://neovim.io/doc/reports/pvs/PVS-studio.html.d/ ) to
see potential bugs found by [PVS Studio ](https://www.viva64.com/en/pvs-studio/ ).
2015-03-09 16:20:15 -07:00
2019-01-08 11:58:06 -07:00
- Use this format for commit messages (where `{id}` is the PVS warning-id)):
```
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.
2015-03-09 16:20:15 -07:00
2019-01-08 11:58:06 -07:00
### Coverity
2016-06-03 12:05:44 -07:00
2019-01-08 11:58:06 -07:00
[Coverity ](https://scan.coverity.com/projects/neovim-neovim ) runs against the
master build. To view the defects, just request access; you will be approved.
2017-04-17 14:52:38 -07:00
2019-01-08 11:58:06 -07:00
- Use this format for commit messages (where `{id}` is the CID (Coverity ID);
([example](https://github.com/neovim/neovim/pull/804))):
```
coverity/{id}: {description}
```
- Search the Neovim commit history to find examples:
```
git log --oneline --no-merges --grep coverity
```
2017-04-17 14:52:38 -07:00
2019-07-19 12:32:04 -07:00
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
The repo includes a `.clang-format` config file which (mostly) matches the
[style-guide]. You can use `clang-format` to format code with the `gq`
operator in Nvim:
if !empty(findfile('.clang-format', ';'))
setlocal formatprg=clang-format\ -style=file
endif
### Navigate
- Use ** [universal-ctags ](https://github.com/universal-ctags/ctags ).**
("Exuberant ctags", the typical `ctags` binary provided by your distro, is
unmaintained and won't recognize many function signatures in Neovim source.)
- Explore the source code [on the web ](https://sourcegraph.com/github.com/neovim/neovim ).
2016-08-09 21:47:04 -07:00
Reviewing
---------
2016-06-03 12:05:44 -07:00
To help review pull requests, start with [this checklist][review-checklist].
2015-03-09 16:20:15 -07:00
Reviewing can be done on GitHub, but you may find it easier to do locally.
2016-06-03 12:05:44 -07:00
Using [`hub`][hub], you can create a new branch with the contents of a pull
request, e.g. [#1820][1820]:
2014-05-07 19:33:41 -07:00
2015-03-09 16:20:15 -07:00
hub checkout https://github.com/neovim/neovim/pull/1820
Use [`git log -p master..FETCH_HEAD`][git-history-filtering] 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.
[gcc-warnings]: https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html
2017-12-27 11:30:23 -07:00
[git-bisect]: http://git-scm.com/book/en/v2/Git-Tools-Debugging-with-Git
2015-03-09 16:20:15 -07:00
[git-feature-branch]: https://www.atlassian.com/git/tutorials/comparing-workflows
[git-history-filtering]: https://www.atlassian.com/git/tutorials/git-log/filtering-the-commit-history
[git-history-rewriting]: http://git-scm.com/book/en/v2/Git-Tools-Rewriting-History
[git-rebasing]: http://git-scm.com/book/en/v2/Git-Branching-Rebasing
[github-issues]: https://github.com/neovim/neovim/issues
2016-06-03 12:05:44 -07:00
[1820]: https://github.com/neovim/neovim/pull/1820
2015-03-09 16:20:15 -07:00
[hub]: https://hub.github.com/
2021-06-10 10:08:58 -07:00
[conventional_commits]: https://www.conventionalcommits.org
2015-04-19 13:17:45 -07:00
[style-guide]: http://neovim.io/develop/style-guide.xml
2016-06-03 12:05:44 -07:00
[ASan]: http://clang.llvm.org/docs/AddressSanitizer.html
2017-11-14 02:47:49 -07:00
[run-tests]: https://github.com/neovim/neovim/blob/master/test/README.md#running-tests
2015-04-21 14:35:06 -07:00
[wiki-faq]: https://github.com/neovim/neovim/wiki/FAQ
2016-06-03 12:05:44 -07:00
[review-checklist]: https://github.com/neovim/neovim/wiki/Code-review-checklist
[3174]: https://github.com/neovim/neovim/issues/3174
2019-01-08 11:58:06 -07:00
[Travis CI]: https://travis-ci.org/neovim/neovim
2019-10-19 18:04:08 -07:00
[sourcehut]: https://builds.sr.ht/~jmk
2017-06-06 06:02:51 -07:00
[AppVeyor]: https://ci.appveyor.com/project/neovim/neovim
[Merge a Vim patch]: https://github.com/neovim/neovim/wiki/Merging-patches-from-upstream-Vim
2019-01-08 11:58:06 -07:00
[Clang report]: https://neovim.io/doc/reports/clang/
2016-08-09 21:47:04 -07:00
[complexity:low]: https://github.com/neovim/neovim/issues?q=is%3Aopen+is%3Aissue+label%3Acomplexity%3Alow
2019-07-19 12:32:04 -07:00
[master error list]: https://raw.githubusercontent.com/neovim/doc/gh-pages/reports/clint/errors.json
2021-01-27 13:15:52 -07:00
[wiki-contribute-help]: https://github.com/neovim/neovim/wiki/contribute-%3Ahelp