Merge pull request #4871 from justinmk/housekeeping

reorg; doc

12 files changed, 89 insertions, 172 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1787a4322b..dbc048d939 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -3,160 +3,96 @@
 ## Getting started
 
 - Help us review [open pull requests](https://github.com/neovim/neovim/pulls)!
-- Look for [entry-level issues][entry-level] to work on.
-    - [Documentation](https://github.com/neovim/neovim/labels/documentation)
-      improvements are also much appreciated.
-- Look at [Waffle][waffle] to see who is working on what issues.
-- If needed, refer to [the wiki][wiki-contributing] for guidance.
+  See [Reviewing](#reviewing) for guidelines.
+- Try an [entry-level issue][entry-level] if you are wondering where to start.
+- Or [merge a Vim patch].
 
 ## Reporting problems
 
-Before reporting an issue, see the following wiki articles:
+- 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.
 
-- [Troubleshooting][wiki-troubleshooting]
-- [Frequently asked questions][wiki-faq]
+### Stages: WIP, RFC
 
-If your issue isn't mentioned there:
+Pull requests are processed in two stages: _WIP_ (Work In Progress) and _RFC_
+(Request For Comment).
 
-- Verify that it hasn't already been reported.
-- If not already running the latest version of Neovim, update to it to see if
-  your problem persists.
-- If you're experiencing compile or runtime warnings/failures, try searching for
-  the error message(s) you received (if any) on [Neovim's issue tracker][github-issues].
-- For runtime issues, try reproducing it using `nvim` with the smallest
-  possible `vimrc` (or none at all via `nvim -u NONE`), to rule out bugs in
-  plugins you're using. If you're using a plugin manager, comment out your
-  plugins, then add them back in one by one.
+- Untagged PRs are assumed to be RFC, meaning 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. This saves time and confusion.
 
-Include as much detail as possible; we generally need to know:
+### Commit messages
 
-- What operating system you're using.
-- Which version of Neovim you're using. To get this, run `nvim --version` from
-  a shell, or run `:version` from inside `nvim`.
-- Whether the bug is present in Vim (not Neovim), and if so which version of
-  Vim. It's fine to report Vim bugs on the Neovim bug tracker, but it saves
-  everyone time if we know from the start that the bug is not a regression
-  caused by Neovim.
-- This isn't required, but what commit introduced the issue for you. You can
-  use [`git bisect`][git-bisect] for this.
+Follow [commit message hygiene][hygiene] to *make reviews easier* and to make
+the VCS/git logs more valuable.
 
-## Submitting contributions
+- 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."
 
-- Make it clear in the issue tracker what you are working on.
-- Be descriptive in your pull request description: what is it for, why is it
-  needed, etc.
-- Do ***not*** make cosmetic changes to unrelated files in the same pull
-  request. This creates noise, making reviews harder to do. If your text
-  editor strips all trailing whitespace in a file when you edit it, disable
-  it.
+### Automated builds (CI)
 
-### Tagging in the issue tracker
+Each pull request must pass the automated builds ([travis CI] and [quickbuild]).
 
-When submitting pull requests (commonly referred to as "PRs"), include one of
-the following tags prepended to the title:
+- 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)
 
-- `[WIP]` - Work In Progress: the PR will change, so while there is no
-  immediate need for review, the submitter still might appreciate it.
-- `[RFC]` - Request For Comment: the PR needs reviewing and/or comments.
-- `[RDY]` - Ready: the PR has been reviewed by at least one other person and
-  has no outstanding issues.
+### Coverity
 
-Assuming the above criteria has been met, feel free to change your PR's tag
-yourself, as opposed to waiting for a contributor to do it for you.
+[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.
 
-### Branching & history
+Use this commit-message format for coverity fixes:
 
-- Do ***not*** work on your PR on the master branch, [use a feature branch
-  instead][git-feature-branch].
-- [Rebase your feature branch onto][git-rebasing] (upstream) master before
-  opening the PR.
-- Keep up to date with changes in (upstream) master so your PR is easy to
-  merge.
-- [Try to actively tidy your history][git-history-rewriting]: combine related
-  commits with interactive rebasing, separate monolithic commits, etc. If your
-  PR is still `[WIP]`, feel free to force-push to your feature branch to tidy
-  your history.
-
-### For code pull requests
-
-#### Testing
-
-We are unlikely to merge your PR if the Travis build fails:
-
-- Travis builds are compiled with the [`-Werror`][gcc-warnings] flag, so if
-  your PR introduces any compiler warnings then the Travis build will fail.
-- If any tests fail, the Travis build will fail.
-  See [Building Neovim#running-tests][wiki-building-running-tests] for
-  information on running tests locally.
-  Tests passing locally doesn't guarantee they'll pass in the Travis
-  build, as different compilers and platforms will be used.
-- Travis runs [Valgrind][valgrind] for the GCC/Linux build, but you may also
-  do so locally by running the following from a shell: `VALGRIND=1 make test`
-
-#### Coding style
-
-We have a [style guide][style-guide] that all new code should follow.
-However, large portions of the existing Vim codebase violate it to some
-degree, and fixing them would increase merge conflicts and add noise to `git
-blame`.
-
-Weigh those costs when making cosmetic changes. In general, avoid pull
-requests dominated by style changes, but feel free to fix up lines that you
-happen to be modifying anyway. Fix anything that looks outright
-[barbarous](http://www.orwell.ru/library/essays/politics/english/e_polit), but
-otherwise prefer to leave things as they are.
-
-For new code, run `make lint` (which runs [clint.py][clint]) to detect style
-errors. It's not perfect, so some warnings may be false positives/negatives.
-To have `clint.py` ignore certain cases, put `// NOLINT` at the end of the
-line.
-
-We also provide a configuration file for [`clang-format`][clang-format], which
-can be used to format code according to the style guidelines. Be aware that
-this formatting method might need user supervision. To have `clang-format`
-ignore certain line ranges, use the following special comments:
-
-```c
-int formatted_code;
-// clang-format off
-    void    unformatted_code  ;
-// clang-format on
-    void formatted_code_again;
-```
-
-### Commit guidelines
-
-The purpose of these guidelines is to *make reviews easier* and make the
-[VCS][vcs] logs more valuable.
+    coverity/<id>: <description of what fixed the defect>
 
-- Try to keep the first line under 72 characters.
-- If necessary, include further description after a blank line.
-    - Don't make the description too verbose by including obvious things, but
-      don't spare clarifications for anything that may be not so obvious.
-      Some commit messages are pages long, and that's fine if there's no
-      better place for those comments to live.
-    - **Recommended:** Prefix logically-related commits with a consistent
-      identifier in each commit message. For already used identifiers, see the
-      commit history for the respective file(s) you're editing.
-      [For example](https://github.com/neovim/neovim/commits?author=elmart),
-      the following commits are related by task (*Introduce nvim namespace*) and
-      sub-task (*Contrib YCM*).
-      <br/> `Introduce nvim namespace: Contrib YCM: Fix style issues`
-      <br/> `Introduce nvim namespace: Contrib YCM: Fix build dir calculation`
-        - Sub-tasks can be *activity-oriented* (doing different things on the same area)
-          or *scope-oriented* (doing the same thing in different areas).
-    - Granularity helps, but it's conceptual size that matters, not extent size.
-- Use the [imperative voice][imperative]: "Fix bug" rather than "Fixed bug" or "Fixes bug."
-
-### Reviewing pull requests
-
-Using a checklist during reviews is highly recommended, so we [provide one at
-the wiki][wiki-review-checklist]. If you think it could be improved, feel free
-to edit it.
+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 do the following to create a new branch with the
-contents of a pull request, such as [#1820][github-pr-1820]:
+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
 
@@ -165,11 +101,7 @@ 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.
 
-You may find it easier to instead use an interactive program for code reviews,
-such as [`tig`][tig].
 
-[clang-format]: http://clang.llvm.org/docs/ClangFormat.html
-[clint]: clint.py
 [entry-level]: https://github.com/neovim/neovim/issues?labels=entry-level&state=open
 [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
@@ -178,16 +110,15 @@ such as [`tig`][tig].
 [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
-[github-pr-1820]: https://github.com/neovim/neovim/pull/1820
+[1820]: https://github.com/neovim/neovim/pull/1820
 [hub]: https://hub.github.com/
-[imperative]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
+[hygiene]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
 [style-guide]: http://neovim.io/develop/style-guide.xml
-[tig]: https://github.com/jonas/tig
-[valgrind]: http://valgrind.org/
-[vcs]: https://en.wikipedia.org/wiki/Revision_control
-[waffle]: https://waffle.io/neovim/neovim
-[wiki-building-running-tests]: https://github.com/neovim/neovim/wiki/Building-Neovim#running-tests
-[wiki-contributing]: https://github.com/neovim/neovim/wiki/Contributing
+[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
-[wiki-review-checklist]: https://github.com/neovim/neovim/wiki/Code-review-checklist
-[wiki-troubleshooting]: https://github.com/neovim/neovim/wiki/Troubleshooting
+[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
+[merge a Vim patch]: https://github.com/neovim/neovim/wiki/Merging-patches-from-upstream-Vim
diff --git a/ISSUE_TEMPLATE.md b/ISSUE_TEMPLATE.md
index d9fd758177..011739396d 100644
--- a/ISSUE_TEMPLATE.md
+++ b/ISSUE_TEMPLATE.md
@@ -1,5 +1,5 @@
-- Neovim version:
-- [ ] Vim behaves differently? Vim version:
+- `nvim --version`:
+- Vim (version: ) behaves differently?
 - Operating system/version:
 - Terminal name/version:
 - `$TERM`:
diff --git a/Makefile b/Makefile
index 9d01347989..5b04b74139 100644
--- a/Makefile
+++ b/Makefile
@@ -119,7 +119,7 @@ install: | nvim
 	+$(BUILD_CMD) -C build install
 
 clint:
-	cmake -DLINT_PRG=./clint.py \
+	cmake -DLINT_PRG=./src/clint.py \
 		-DLINT_DIR=src \
 		-DLINT_SUPPRESS_URL="$(DOC_DOWNLOAD_URL_BASE)$(CLINT_ERRORS_FILE_PATH)" \
 		-P cmake/RunLint.cmake
diff --git a/README.md b/README.md
index c6f668c425..63c7dd95d7 100644
--- a/README.md
+++ b/README.md
@@ -18,7 +18,7 @@
 
 Neovim is a project that seeks to aggressively refactor Vim in order to:
 
-- Simplify maintenance and encourage [contributions](https://github.com/neovim/neovim/wiki/Contributing)
+- Simplify maintenance and encourage [contributions](CONTRIBUTING.md)
 - Split the work between multiple developers
 - Enable the implementation of new/modern user interfaces without any
   modifications to the core source
@@ -42,7 +42,7 @@ See the [progress page](https://github.com/neovim/neovim/wiki/Progress) for a co
 
 ### What's being worked on now
 
-- Port all IO to [libuv](https://github.com/libuv/libuv/blob/master/README.md)
+- Port all IO to [libuv](https://github.com/libuv/libuv/)
 - Convert legacy tests to Lua tests
 - VimL => Lua translator
 
@@ -51,10 +51,6 @@ See the [progress page](https://github.com/neovim/neovim/wiki/Progress) for a co
 There is a formula for OSX/homebrew, a PKGBUILD for Arch Linux, RPM, deb, and
 more. See [the wiki](https://github.com/neovim/neovim/wiki/Installing-Neovim)!
 
-### Contributing
-
-...would be awesome! See [the wiki](https://github.com/neovim/neovim/wiki/Contributing) for more details.
-
 ### License
 
 Neovim is licensed under the terms of the Apache 2.0 license, except for
diff --git a/neovim.rb b/neovim.rb
deleted file mode 100644
index 859ebdf39d..0000000000
--- a/neovim.rb
+++ /dev/null
@@ -1,9 +0,0 @@
-odie <<-EOS.undent
-
-  Whoops, the neovim Homebrew Formula has moved! Please instead run:
-
-    brew tap neovim/homebrew-neovim
-    brew install --HEAD neovim
-
-  Thanks!
-EOS
diff --git a/.asan-blacklist b/src/.asan-blacklist
index 63558170b3..63558170b3 100644
--- a/.asan-blacklist
+++ b/src/.asan-blacklist
diff --git a/.valgrind.supp b/src/.valgrind.supp
index 8b630fcaaf..8b630fcaaf 100644
--- a/.valgrind.supp
+++ b/src/.valgrind.supp
diff --git a/Doxyfile b/src/Doxyfile
index de31c8355f..de31c8355f 100644
--- a/Doxyfile
+++ b/src/Doxyfile
diff --git a/clint.py b/src/clint.py
index c19ba4b7ae..c19ba4b7ae 100755
--- a/clint.py
+++ b/src/clint.py
diff --git a/src/nvim/CMakeLists.txt b/src/nvim/CMakeLists.txt
index ab6f69f66c..5a3db74903 100644
--- a/src/nvim/CMakeLists.txt
+++ b/src/nvim/CMakeLists.txt
@@ -269,7 +269,7 @@ if(CLANG_ASAN_UBSAN)
     set(SANITIZE_RECOVER -fno-sanitize-recover)         # Clang 3.5-
   endif()
   set_property(TARGET nvim APPEND_STRING PROPERTY COMPILE_FLAGS "-DEXITFREE ")
-  set_property(TARGET nvim APPEND_STRING PROPERTY COMPILE_FLAGS "${SANITIZE_RECOVER} -fno-omit-frame-pointer -fno-optimize-sibling-calls -fsanitize=address -fsanitize=undefined -fsanitize-blacklist=${PROJECT_SOURCE_DIR}/.asan-blacklist")
+  set_property(TARGET nvim APPEND_STRING PROPERTY COMPILE_FLAGS "${SANITIZE_RECOVER} -fno-omit-frame-pointer -fno-optimize-sibling-calls -fsanitize=address -fsanitize=undefined -fsanitize-blacklist=${PROJECT_SOURCE_DIR}/src/.asan-blacklist")
   set_property(TARGET nvim APPEND_STRING PROPERTY LINK_FLAGS "-fsanitize=address -fsanitize=undefined ")
 elseif(CLANG_MSAN)
   message(STATUS "Enabling Clang memory sanitizer for nvim.")
diff --git a/src/nvim/eval.c b/src/nvim/eval.c
index 92e572db2f..7edf511c18 100644
--- a/src/nvim/eval.c
+++ b/src/nvim/eval.c
@@ -22111,9 +22111,8 @@ bool eval_has_provider(char *name)
   return false;
 }
 
-// Compute the `DictWatcher` address from a QUEUE node. This only exists because
-// ASAN doesn't handle `QUEUE_DATA` pointer arithmetic, and we blacklist this
-// function on .asan-blacklist.
+// Compute the `DictWatcher` address from a QUEUE node. This only exists for
+// .asan-blacklist (ASAN doesn't handle QUEUE_DATA pointer arithmetic).
 static DictWatcher *dictwatcher_node_data(QUEUE *q)
   FUNC_ATTR_NONNULL_ALL FUNC_ATTR_NONNULL_RET
 {
diff --git a/src/nvim/testdir/Makefile b/src/nvim/testdir/Makefile
index 94643bc843..b06efc9ffb 100644
--- a/src/nvim/testdir/Makefile
+++ b/src/nvim/testdir/Makefile
@@ -60,7 +60,7 @@ ifdef USE_VALGRIND
 	TOOL := valgrind -q                                     \
 	                 -q                                     \
 	                 $(VALGRIND_TOOL)                       \
-	                 --suppressions=../../../.valgrind.supp \
+	                 --suppressions=../../.valgrind.supp \
 	                 --error-exitcode=123                   \
 	                 --log-file=valgrind.\%p.$*             \
 	                 $(VGDB)                                \