You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

239 lines
9.4 KiB

5 years ago
5 years ago
5 years ago
5 years ago
4 years ago
5 years ago
5 years ago
  1. Contributing to Neovim
  2. ======================
  3. Getting started
  4. ---------------
  5. If you want to help but don't know where to start, here are some
  6. low-risk/isolated tasks:
  7. - [Merge a Vim patch].
  8. - Try a [good first issue](../../labels/good%20first%20issue) or [complexity:low] issue.
  9. - Fix bugs found by [Clang](#clang-scan-build), [PVS](#pvs-studio) or
  10. [Coverity](#coverity).
  11. Reporting problems
  12. ------------------
  13. - [Check the FAQ][wiki-faq].
  14. - [Search existing issues][github-issues] (including closed!)
  15. - Update Neovim to the latest version to see if your problem persists.
  16. - Disable plugins incrementally, to narrow down the cause of the issue.
  17. - When reporting a crash, [include a stacktrace](https://github.com/neovim/neovim/wiki/FAQ#backtrace-linux).
  18. - [Bisect][git-bisect] to the cause of a regression, if you are able. This is _extremely_ helpful.
  19. - Check `$NVIM_LOG_FILE`, if it exists.
  20. - Include `cmake --system-information` for build-related issues.
  21. Developer guidelines
  22. --------------------
  23. - Nvim contributors should read `:help dev`.
  24. - External UI developers should read `:help dev-ui`.
  25. - API client developers should read `:help dev-api-client`.
  26. - Nvim developers are _strongly encouraged_ to install `ninja` for faster builds.
  27. ```
  28. sudo apt-get install ninja-build
  29. make distclean
  30. make # Nvim build system uses ninja automatically, if available.
  31. ```
  32. - [Improve documentation][wiki-contribute-help]
  33. Pull requests (PRs)
  34. ---------------------
  35. - To avoid duplicate work, create a `[WIP]` pull request as soon as possible.
  36. - Your PR must include **test coverage.** See [test/README.md][run-tests].
  37. - Avoid cosmetic changes to unrelated files in the same commit.
  38. - Use a [feature branch][git-feature-branch] instead of the master branch.
  39. - Use a **rebase workflow** for small PRs.
  40. - After addressing review comments, it's fine to rebase and force-push.
  41. - Use a **merge workflow** for big, high-risk PRs.
  42. - Merge `master` into your PR when there are conflicts or when master
  43. introduces breaking changes.
  44. - Use the `ri` git alias:
  45. ```
  46. [alias]
  47. 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\" \"$@\"'"
  48. ```
  49. This avoids unnecessary rebases yet still allows you to combine related
  50. commits, separate monolithic commits, etc.
  51. - Do not edit commits that come before the merge commit.
  52. - During a squash/fixup, use `exec make -C build unittest` between each
  53. pick/edit/reword.
  54. ### Stages: WIP, RFC, RDY
  55. Pull requests have three stages: `[WIP]` (Work In Progress), `[RFC]` (Request
  56. For Comment) and `[RDY]` (Ready).
  57. 1. `[RFC]` is assumed by default, **do not** put "RFC" in the PR title (it adds
  58. noise to merge commit messages).
  59. 2. Add `[WIP]` to the PR title if you are _not_ requesting feedback and the work
  60. is still in flux.
  61. 3. Add `[RDY]` to the PR title if you are _done_ and only waiting on merge.
  62. ### Commit messages
  63. Follow [commit message hygiene][hygiene] to *make reviews easier* and to make
  64. the VCS/git logs more valuable.
  65. - Try to keep the first line under 72 characters.
  66. - **Prefix the commit subject with a _scope_:** `doc:`, `test:`, `foo.c:`,
  67. `runtime:`, ...
  68. - Subject line for commits with only style/lint changes can be a single
  69. word: `style` or `lint`.
  70. - A blank line must separate the subject from the description.
  71. - Use the _imperative voice_: "Fix bug" rather than "Fixed bug" or "Fixes bug."
  72. ### Automated builds (CI)
  73. Each pull request must pass the automated builds on [Travis CI], [sourcehut]
  74. and [AppVeyor].
  75. - CI builds are compiled with [`-Werror`][gcc-warnings], so compiler warnings
  76. will fail the build.
  77. - If any tests fail, the build will fail.
  78. See [test/README.md#running-tests][run-tests] to run tests locally.
  79. Passing locally doesn't guarantee passing the CI build, because of the
  80. different compilers and platforms tested against.
  81. - CI runs [ASan] and other analyzers.
  82. - To run valgrind locally: `VALGRIND=1 make test`
  83. - To run Clang ASan/UBSan locally: `CC=clang make CMAKE_FLAGS="-DCLANG_ASAN_UBSAN=ON"`
  84. - The [lint](#lint) build checks modified lines _and their immediate
  85. neighbors_, to encourage incrementally updating the legacy style to meet our
  86. [style](#style). (See [#3174][3174] for background.)
  87. - CI for freebsd and openbsd runs on [sourcehut].
  88. - To get a backtrace on freebsd (after connecting via ssh):
  89. ```sh
  90. sudo pkg install tmux # If you want tmux.
  91. lldb build/bin/nvim -c nvim.core
  92. # To get a full backtrace:
  93. # 1. Rebuild with debug info.
  94. rm -rf nvim.core build
  95. gmake CMAKE_BUILD_TYPE=RelWithDebInfo CMAKE_EXTRA_FLAGS="-DCI_BUILD=ON -DMIN_LOG_LEVEL=3" nvim
  96. # 2. Run the failing test to generate a new core file.
  97. TEST_FILE=test/functional/foo.lua gmake functionaltest
  98. lldb build/bin/nvim -c nvim.core
  99. ```
  100. ### Clang scan-build
  101. View the [Clang report] to see potential bugs found by the Clang
  102. [scan-build](https://clang-analyzer.llvm.org/scan-build.html) analyzer.
  103. - Search the Neovim commit history to find examples:
  104. ```
  105. git log --oneline --no-merges --grep clang
  106. ```
  107. - To verify a fix locally, run `scan-build` like this:
  108. ```
  109. rm -rf build/
  110. scan-build --use-analyzer=/usr/bin/clang make
  111. ```
  112. ### PVS-Studio
  113. View the [PVS report](https://neovim.io/doc/reports/pvs/PVS-studio.html.d/) to
  114. see potential bugs found by [PVS Studio](https://www.viva64.com/en/pvs-studio/).
  115. - Use this format for commit messages (where `{id}` is the PVS warning-id)):
  116. ```
  117. PVS/V{id}: {description}
  118. ```
  119. - Search the Neovim commit history to find examples:
  120. ```
  121. git log --oneline --no-merges --grep PVS
  122. ```
  123. - Try `./scripts/pvscheck.sh` to run PVS locally.
  124. ### Coverity
  125. [Coverity](https://scan.coverity.com/projects/neovim-neovim) runs against the
  126. master build. To view the defects, just request access; you will be approved.
  127. - Use this format for commit messages (where `{id}` is the CID (Coverity ID);
  128. ([example](https://github.com/neovim/neovim/pull/804))):
  129. ```
  130. coverity/{id}: {description}
  131. ```
  132. - Search the Neovim commit history to find examples:
  133. ```
  134. git log --oneline --no-merges --grep coverity
  135. ```
  136. Coding
  137. ------
  138. ### Lint
  139. You can run the linter locally by:
  140. make lint
  141. The lint step downloads the [master error list] and excludes them, so only lint
  142. errors related to the local changes are reported.
  143. You can lint a single file (but this will _not_ exclude legacy errors):
  144. ./src/clint.py src/nvim/ops.c
  145. ### Style
  146. The repo includes a `.clang-format` config file which (mostly) matches the
  147. [style-guide]. You can use `clang-format` to format code with the `gq`
  148. operator in Nvim:
  149. if !empty(findfile('.clang-format', ';'))
  150. setlocal formatprg=clang-format\ -style=file
  151. endif
  152. ### Navigate
  153. - Use **[universal-ctags](https://github.com/universal-ctags/ctags).**
  154. ("Exuberant ctags", the typical `ctags` binary provided by your distro, is
  155. unmaintained and won't recognize many function signatures in Neovim source.)
  156. - Explore the source code [on the web](https://sourcegraph.com/github.com/neovim/neovim).
  157. Reviewing
  158. ---------
  159. To help review pull requests, start with [this checklist][review-checklist].
  160. Reviewing can be done on GitHub, but you may find it easier to do locally.
  161. Using [`hub`][hub], you can create a new branch with the contents of a pull
  162. request, e.g. [#1820][1820]:
  163. hub checkout https://github.com/neovim/neovim/pull/1820
  164. Use [`git log -p master..FETCH_HEAD`][git-history-filtering] to list all
  165. commits in the feature branch which aren't in the `master` branch; `-p`
  166. shows each commit's diff. To show the whole surrounding function of a change
  167. as context, use the `-W` argument as well.
  168. [gcc-warnings]: https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html
  169. [git-bisect]: http://git-scm.com/book/en/v2/Git-Tools-Debugging-with-Git
  170. [git-feature-branch]: https://www.atlassian.com/git/tutorials/comparing-workflows
  171. [git-history-filtering]: https://www.atlassian.com/git/tutorials/git-log/filtering-the-commit-history
  172. [git-history-rewriting]: http://git-scm.com/book/en/v2/Git-Tools-Rewriting-History
  173. [git-rebasing]: http://git-scm.com/book/en/v2/Git-Branching-Rebasing
  174. [github-issues]: https://github.com/neovim/neovim/issues
  175. [1820]: https://github.com/neovim/neovim/pull/1820
  176. [hub]: https://hub.github.com/
  177. [hygiene]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
  178. [style-guide]: http://neovim.io/develop/style-guide.xml
  179. [ASan]: http://clang.llvm.org/docs/AddressSanitizer.html
  180. [run-tests]: https://github.com/neovim/neovim/blob/master/test/README.md#running-tests
  181. [wiki-faq]: https://github.com/neovim/neovim/wiki/FAQ
  182. [review-checklist]: https://github.com/neovim/neovim/wiki/Code-review-checklist
  183. [3174]: https://github.com/neovim/neovim/issues/3174
  184. [Travis CI]: https://travis-ci.org/neovim/neovim
  185. [sourcehut]: https://builds.sr.ht/~jmk
  186. [AppVeyor]: https://ci.appveyor.com/project/neovim/neovim
  187. [Merge a Vim patch]: https://github.com/neovim/neovim/wiki/Merging-patches-from-upstream-Vim
  188. [Clang report]: https://neovim.io/doc/reports/clang/
  189. [complexity:low]: https://github.com/neovim/neovim/issues?q=is%3Aopen+is%3Aissue+label%3Acomplexity%3Alow
  190. [master error list]: https://raw.githubusercontent.com/neovim/doc/gh-pages/reports/clint/errors.json
  191. [wiki-contribute-help]: https://github.com/neovim/neovim/wiki/contribute-%3Ahelp