1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
|
# Contributing to Neovim
Getting started
---------------
If you want to help but don't know where to start, here are some
low-risk/isolated tasks:
- Help us [review pull requests](#reviewing)!
- Merge a [Vim patch].
- Try a [complexity:low] issue.
- Fix [clang-scan] or [coverity](#coverity) warnings.
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.
- If you're using a plugin manager, comment out your plugins, then add them back
in one by one, to narrow down the cause of the issue.
- Crash reports which include a stacktrace are 10x more valuable.
- [Bisecting][git-bisect] to the cause of a regression often leads to an
immediate fix.
Pull requests ("PRs")
---------------------
- To avoid duplicate work, you may want to create a `[WIP]` pull request so that
others know what you are working on.
- Avoid cosmetic changes to unrelated files in the same commit: extra noise
makes reviews more difficult.
- Use a [feature branch][git-feature-branch] instead of the master branch.
- [Rebase your feature branch][git-rebasing] onto (upstream) master before
opening the PR.
- After addressing the review comments, it's fine to rebase and force-push to
your review.
- Try to [tidy your history][git-history-rewriting]: combine related commits
with interactive rebasing, separate monolithic commits, etc.
### Stages: WIP, RFC
Pull requests have two stages: `[WIP]` (Work In Progress) and `[RFC]` (Request
For Comment).
- Untagged PRs are assumed to be `[RFC]`, i.e. the work is ready for review and
you would like feedback.
- Preprend `[WIP]` to the PR title if you are _not_ ready for feedback and the
work is still in flux.
### Commit messages
Follow [commit message hygiene][hygiene] to *make reviews easier* and to make
the VCS/git logs more valuable.
- Try to keep the first line under 72 characters.
- **Prefix the commit subject with a _scope_:** `doc:`, `test:`, `foo.c:`,
`runtime:`, ...
- For commits that contain only style/lint changes, a single-word subject
line is preferred: `style` or `lint`.
- A blank line must separate the subject from the description.
- Use the _imperative voice_: "Fix bug" rather than "Fixed bug" or "Fixes bug."
### Automated builds (CI)
Each pull request must pass the automated builds ([travis CI] and [quickbuild]).
- CI builds are compiled with [`-Werror`][gcc-warnings], so if your PR
introduces any compiler warnings, the build will fail.
- If any tests fail, the build will fail.
See [Building Neovim#running-tests][wiki-run-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`
- The `lint` build ([#3174][3174]) checks modified lines _and their immediate
neighbors_. This is to encourage incrementally updating the legacy style to
meet our style guidelines.
- A single word (`lint` or `style`) is sufficient as the subject line of
a commit that contains only style changes.
- [How to investigate QuickBuild failures](https://github.com/neovim/neovim/pull/4718#issuecomment-217631350)
### Coverity
[Coverity](https://scan.coverity.com/projects/neovim-neovim) runs against the
master build. If you want to view the defects, just request access at the
_Contributor_ level. An Admin will grant you permission.
Use this commit-message format for coverity fixes:
coverity/<id>: <description of what fixed the defect>
where `<id>` is the Coverity ID (CID). For example see [#804](https://github.com/neovim/neovim/pull/804).
Reviewing
---------
To help review pull requests, start with [this checklist][review-checklist].
Reviewing can be done on GitHub, but you may find it easier to do locally.
Using [`hub`][hub], you can create a new branch with the contents of a pull
request, e.g. [#1820][1820]:
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
[git-bisect]: http://git-scm.com/book/tr/v2/Git-Tools-Debugging-with-Git
[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
[1820]: https://github.com/neovim/neovim/pull/1820
[hub]: https://hub.github.com/
[hygiene]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
[style-guide]: http://neovim.io/develop/style-guide.xml
[ASan]: http://clang.llvm.org/docs/AddressSanitizer.html
[wiki-run-tests]: https://github.com/neovim/neovim/wiki/Building-Neovim#running-tests
[wiki-faq]: https://github.com/neovim/neovim/wiki/FAQ
[review-checklist]: https://github.com/neovim/neovim/wiki/Code-review-checklist
[3174]: https://github.com/neovim/neovim/issues/3174
[travis CI]: https://travis-ci.org/neovim/neovim
[quickbuild]: http://neovim-qb.szakmeister.net/dashboard
[Vim patch]: https://github.com/neovim/neovim/wiki/Merging-patches-from-upstream-Vim
[clang-scan]: https://neovim.io/doc/reports/clang/
[complexity:low]: https://github.com/neovim/neovim/issues?q=is%3Aopen+is%3Aissue+label%3Acomplexity%3Alow
|
