neovim/CONTRIBUTING.md

Contributing to Neovim

Getting started

• Help us review open pull requests!
• Look for entry-level issues to work on.
  • documentation improvements are also very helpful.
• Look at Waffle to see who is working on what issues.
• Refer to the the 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.

Please run clint.py 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, the following commits are related by task (Introduce vim namespace) and scope (Contrib YCM).
    Introduce vim namespace: Contrib YCM: Fix style issues.
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."