Update CONTRIBUTING.md and README.md #740

- recommend task/subtask convention for commit messages

CONTRIBUTING.md

@@ -1,11 +1,13 @@
 # Contributing to Neovim
 
-If you need additional support see [the wiki][wiki].
+## Getting started
 
-## Getting started contributing
+- Help us review [open pull requests](https://github.com/neovim/neovim/pulls)!
-
+- Look for [**entry-level**][entry] issues to work on.
-- Look for the [`entry-level`][entry] Issue Label. It marks easier issues.
+    - [**documentation**](https://github.com/neovim/neovim/labels/documentation)
-- Take a look at [Waffle][waffle]. It'll show who is working on what isssues.
+      improvements are also very helpful.
+- Look at [Waffle][waffle] to see who is working on what issues.
+- Refer to the [the wiki][wiki] for detailed guidance.
 
 ### What not to do
 
@@ -20,23 +22,20 @@ excessive noise to `git blame`.
 
 ## Pull requests
 
-### For all PRs
-
 - Make it clear in the issue tracker what you are working on.
 - Be descriptive in your PR message: what is it for, why is it needed, etc.
 - Don't make cosmetic changes to unrelated files in the same PR.
 
 #### Tagging in the issue tracker
 
-When submitting pull requests, include one of the following 'tags' in the title:
+When submitting pull requests, include one of the following tokens in the title:
 
 * `[WIP]` - Work In Progress. The pull request will change, and there is no need
   to review it yet.
 * `[RFC]` - Request For Comment. The request needs reviewing and/or comments.
 * `[RDY]` - The request is ready to be merged. The request must have been
   reviewed by at least one person and have no outstanding issues.
-* Default label is assumed to be `[WIP]` as long as there's no indication
+* Default label is assumed to be `[WIP]` if there's no indication otherwise.
-  otherwise.
 
 #### Branching & history
 
@@ -52,34 +51,43 @@ When submitting pull requests, include one of the following 'tags' in the title:
 #### Testing
 
 - We are unlikely to merge your PR if the Travis build fails.
-- The Travis build does not currently run the tests under valgrind, but we would
+- The Travis build does not currently run the tests under valgrind, but you
-  strongly encourage you to do so locally.
+  are encouraged to do so locally.
 
 #### Coding style
 
-All code changes should follow the [Neovim style guide][style].
+Code changes should follow the [Neovim style guide][style].
 
 Please run [`clint.py`][clint] to detect style errors. It is not perfect and may
 have false positives and negatives. To have `clint.py` ignore certain special
 cases, put `// NOLINT` at the end of the line.
 
-#### Commit messages
+#### Commit guidelines
 
-Follow the [Tim Pope Convention][commit] (@tpope) for commit messages. Most
+The purpose of these guidelines is to *make reviews easier* and make the VCS logs more valuable.
-importantly, do the following:
 
-- Keep the first line a summary of 50 characters or less.
+- Try to keep the first line under 70 characters.
-- Write the summary in the [imperative mood][imperative].
+- Include further description, if necessary, after a blank line.
-- Write a more detailed explanation (after a blank line) that explains more in
+    - Don't make it too verbose by including obvious things.
-  depth (only if necessary).
+    - But don't spare clarifications for anything that could 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 at the beginning of each commit message.
+      [For example](https://github.com/neovim/neovim/commits?author=elmart),
+      the following commits are related by task (*Introduce vim namespace*) and
+      scope (*Contrib YCM*).
+      <br/> `Introduce vim namespace: Contrib YCM: Fix style issues.`
+      <br/> `Introduce vim namespace: Contrib YCM: Fix build dir calculation`
+        - Subtasks can be *activity-oriented* (doing different things on the same area)
+          or *scope-oriented* (doing the same thing on different areas).
+    - Granularity helps, but it's conceptual size that matters, not extent size.
+- Use the imperative voice: "Fix bug" rather than "Fixed bug" or "Fixes bug."
 
-Take a look at @elmart's [commits on Neovim][elmart] for examples.
 
 [clint]: clint.py
-[commit]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
 [entry]: https://github.com/neovim/neovim/issues?labels=entry-level&state=open
-[elmart]: https://github.com/neovim/neovim/commits?author=elmart
+[imperative]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
-[imperative]: http://en.wikipedia.org/wiki/Imperative_mood
 [style]: http://neovim.org/develop/style-guide.xml
 [waffle]: https://waffle.io/neovim/neovim
 [wiki]: https://github.com/neovim/neovim/wiki/Contributing

README.md

@@ -1,7 +1,9 @@
 ![Neovim](https://raw.githubusercontent.com/neovim/neovim.github.io/master/logos/neovim-logo.png)
 
 [Website](http://neovim.org) |
-[Google Group](https://groups.google.com/forum/#!forum/neovim) |
+[Wiki](https://github.com/neovim/neovim/wiki) |
+[Documentation](http://neovim.org/doc) |
+[Mailing List](https://groups.google.com/forum/#!forum/neovim) |
 [Twitter](http://twitter.com/Neovim) |
 [Reddit](http://www.reddit.com/r/neovim) |
 [Bountysource](https://www.bountysource.com/teams/neovim)
@@ -11,59 +13,35 @@
 [![Coverage Status](https://img.shields.io/coveralls/neovim/neovim.svg)](https://coveralls.io/r/neovim/neovim)
 [![Coverity Scan Build](https://scan.coverity.com/projects/2227/badge.svg)](https://scan.coverity.com/projects/2227)
 [![Clang Scan Build](http://neovim.org/doc/reports/clang/badge.svg)](http://neovim.org/doc/reports/clang)
-[![Bountysource](https://www.bountysource.com/badge/tracker?tracker_id=461131)](https://www.bountysource.com/trackers/461131-neovim?utm_source=461131&utm_medium=shield&utm_campaign=TRACKER_BADGE)
 
 Neovim is a project that seeks to aggressively refactor Vim in order to:
 
-- Simplify maintenance and encourage contributions
+- Simplify maintenance and encourage [contributions](https://github.com/neovim/neovim/wiki/Contributing)
 - Split the work between multiple developers
 - Enable the implementation of new/modern user interfaces without any
   modifications to the core source
-- Improve extensibility with a new plugin architecture
+- Improve extensibility with a new [plugin architecture](https://github.com/neovim/neovim/wiki/Plugin-UI-architecture)
 
 For lots more details, see
 [the wiki](https://github.com/neovim/neovim/wiki/Introduction)!
 
 ### What's been done so far
 
-- Cleaned up source tree, leaving only core files
+- [Job control](https://github.com/neovim/neovim/pull/475) (work with processes asynchronously)
-- Removed support for legacy systems and moved to C99
+- msgpack remote API
-    - Removed tons of `FEAT_*` macros with [unifdef]
+- Performance, reliability, and portability improvements
-    - Reduced C code from 300k lines to 170k
+- See the [progress page](https://github.com/neovim/neovim/wiki/Progress) for a comprehensive list.
-- Enabled modern compiler features and [optimizations](https://github.com/neovim/neovim/pull/426)
-- Formatted entire source with [uncrustify]
-- Replaced autotools build system with [CMake]
-- Implemented [continuous integration] and [test coverage]
-- Wrote 100+ new unit tests
-- Split large, monolithic files (`misc1.c`) into logical units
-  (`path.c`, `indent.c`, `garray.c`, `keymap.c`, ...)
-- [Implemented](https://github.com/neovim/neovim/pull/475) job control ("async")
-- Reworked out-of-memory handling resulting in greatly simplified control flow
-- Merged 50+ upstream patches (nearly caught up with upstream)
-- [Removed](https://github.com/neovim/neovim/pull/635) 8.3 filename support
-- [Changed](https://github.com/neovim/neovim/pull/574) to portable format
-  specifiers (first step towards building on Windows)
-
-[unifdef]: http://freecode.com/projects/unifdef
-[uncrustify]: http://uncrustify.sourceforge.net/
-[CMake]: http://cmake.org/
-[continuous integration]: https://travis-ci.org/neovim/neovim
-[test coverage]: https://coveralls.io/r/neovim/neovim
 
 ### What's being worked on now
 
-- Porting all IO to libuv
+- Port all IO to libuv
 - Lots of refactoring
 - A VimL => Lua transpiler
-- Formatting with `clint.py`
-- msg-pack remote API
 
 ### How do I get it?
 
-There is a formula for OSX/homebrew, a PKGBUILD for Arch Linux,
+There is a formula for OSX/homebrew, a PKGBUILD for Arch Linux, RPM, deb, and
-and detailed instructions for building on other OSes.
+more. See [the wiki](https://github.com/neovim/neovim/wiki/Installing)!
-
-See [the wiki](https://github.com/neovim/neovim/wiki/Installing)!
 
 ### Community