diff options
Diffstat (limited to 'CONTRIBUTING.md')
| -rw-r--r-- | CONTRIBUTING.md | 49 |
1 files changed, 17 insertions, 32 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 582d5fbdd4..03fe48fed7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,7 +10,7 @@ low-risk/isolated tasks: - Try a [complexity:low] issue. - Fix bugs found by [Clang](#clang-scan-build), [PVS](#pvs-studio) or [Coverity](#coverity). -- [Improve documentation][wiki-contribute-help] +- [Improve documentation](#documenting) - [Merge a Vim patch] (familiarity with Vim is *strongly* recommended) Reporting problems @@ -30,9 +30,9 @@ Reporting problems 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. +- Read [:help dev](https://neovim.io/doc/user/develop.html#dev) if you are working on Nvim core. +- Read [:help dev-ui](https://neovim.io/doc/user/develop.html#dev-ui) if you are developing a UI. +- Read [:help dev-api-client](https://neovim.io/doc/user/develop.html#dev-api-client) if you are developing an API client. - Install `ninja` for faster builds of Nvim. ``` sudo apt-get install ninja-build @@ -47,21 +47,19 @@ Pull requests (PRs) - Your PR must include [test coverage][run-tests]. - Avoid cosmetic changes to unrelated files in the same commit. - Use a [feature branch][git-feature-branch] instead of the master branch. -- 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. +- 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. - - Use the `ri` git alias: - ``` - [alias] - 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\" \"$@\"'" - ``` - This avoids unnecessary rebases yet still allows you to combine related - commits, separate monolithic commits, etc. - 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. + +### 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 @@ -111,7 +109,7 @@ the VCS/git logs more valuable. The general structure of a commit message is: ### Automated builds (CI) -Each pull request must pass the automated builds on [sourcehut] and [GitHub Actions]. +Each pull request must pass the automated builds on [Cirrus CI] and [GitHub Actions]. - CI builds are compiled with [`-Werror`][gcc-warnings], so compiler warnings will fail the build. @@ -125,20 +123,7 @@ Each pull request must pass the automated builds on [sourcehut] and [GitHub Acti - 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.) -- 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 - gmake CMAKE_BUILD_TYPE=RelWithDebInfo CMAKE_EXTRA_FLAGS="-DCI_BUILD=ON -DMIN_LOG_LEVEL=3" nvim - # 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 - ``` +- CI for FreeBSD runs on [Cirrus CI]. ### Clang scan-build @@ -321,6 +306,7 @@ as context, use the `-W` argument as well. [1820]: https://github.com/neovim/neovim/pull/1820 [3174]: https://github.com/neovim/neovim/issues/3174 [ASan]: http://clang.llvm.org/docs/AddressSanitizer.html +[Cirrus CI]: https://cirrus-ci.com/github/neovim/neovim [Clang report]: https://neovim.io/doc/reports/clang/ [GitHub Actions]: https://github.com/neovim/neovim/actions [clangd]: https://clangd.llvm.org @@ -345,7 +331,6 @@ as context, use the `-W` argument as well. [pr-ready]: https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request [review-checklist]: https://github.com/neovim/neovim/wiki/Code-review-checklist [run-tests]: https://github.com/neovim/neovim/blob/master/test/README.md#running-tests -[sourcehut]: https://builds.sr.ht/~jmk [style-guide]: https://neovim.io/doc/user/dev_style.html#dev-style [uncrustify]: http://uncrustify.sourceforge.net/ [wiki-contribute-help]: https://github.com/neovim/neovim/wiki/contribute-%3Ahelp |