Update CONTRIBUTING.md and README.md #740

- recommend task/subtask convention for commit messages
This commit is contained in:
Justin M. Keyes 2014-05-20 14:17:43 -04:00
parent c2a8f06bba
commit 062402fb64
2 changed files with 44 additions and 58 deletions

View File

@ -1,11 +1,13 @@
# Contributing to Neovim
If you need additional support see [the wiki][wiki].
## Getting started
## Getting started contributing
- Look for the [`entry-level`][entry] Issue Label. It marks easier issues.
- Take a look at [Waffle][waffle]. It'll show who is working on what isssues.
- Help us review [open pull requests](https://github.com/neovim/neovim/pulls)!
- Look for [**entry-level**][entry] issues to work on.
- [**documentation**](https://github.com/neovim/neovim/labels/documentation)
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
otherwise.
* Default label is assumed to be `[WIP]` if there's no indication 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
strongly encourage you to do so locally.
- The Travis build does not currently run the tests under valgrind, but you
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
importantly, do the following:
The purpose of these guidelines is to *make reviews easier* and make the VCS logs more valuable.
- Keep the first line a summary of 50 characters or less.
- Write the summary in the [imperative mood][imperative].
- Write a more detailed explanation (after a blank line) that explains more in
depth (only if necessary).
- Try to keep the first line under 70 characters.
- Include further description, if necessary, after a blank line.
- Don't make it too verbose by including obvious things.
- 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://en.wikipedia.org/wiki/Imperative_mood
[imperative]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
[style]: http://neovim.org/develop/style-guide.xml
[waffle]: https://waffle.io/neovim/neovim
[wiki]: https://github.com/neovim/neovim/wiki/Contributing

View File

@ -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
- Removed support for legacy systems and moved to C99
- Removed tons of `FEAT_*` macros with [unifdef]
- Reduced C code from 300k lines to 170k
- 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
- [Job control](https://github.com/neovim/neovim/pull/475) (work with processes asynchronously)
- msgpack remote API
- Performance, reliability, and portability improvements
- See the [progress page](https://github.com/neovim/neovim/wiki/Progress) for a comprehensive list.
### 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,
and detailed instructions for building on other OSes.
See [the wiki](https://github.com/neovim/neovim/wiki/Installing)!
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)!
### Community