# Contributing to Neovim

## Getting started

- 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

Please avoid broad cosmetic/style changes which increase merge conflicts and add
excessive noise to `git blame`.

## Issues

- Search existing issues before raising a new one.
- Include as much detail as possible. In particular, we need to know which
  OS you're using.

## Pull requests

- 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 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]` if there's no indication otherwise.

#### Branching & history

- Use a feature branch, not master.
- Rebase your feature branch onto (upstream) master before raising the PR.
- Keep up to date with changes in (upstream) master so your PR is easy to merge.
- Try to actively tidy your history: combine related commits with interactive
  rebasing etc. If your PR is still `[WIP]` don't be afraid to force-push to
  your feature branch to tidy your history.

### For code PRs

#### 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 you
  are encouraged to do so locally.

#### Coding 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 guidelines

The purpose of these guidelines is to *make reviews easier* and make the VCS logs more valuable.

- 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."


[clint]: clint.py
[entry]: https://github.com/neovim/neovim/issues?labels=entry-level&state=open
[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