Contributing

One of the great things about open source projects is that anyone can contribute in any number of meaningful ways. ESLint couldn’t exist without the help of the many contributors its had since the project began, and we want you to feel like you can contribute and make a difference as well.

This guide is intended for anyone who wants to contribute to an ESLint project. Please read it carefully as it answers a lot of the questions many newcomers have when first working with our projects.

In order to submit code or documentation to an ESLint project, please electronically sign the Contributor License Agreement. It is very important that you read and understand the CLA, as it gives us the right to use your contribution.

Ways to Contribute

There are many different ways you can contribute:

For each way to contribute, there are some specific guidelines to keep in mind.

Filing Issues

You can file an issue directly inside of our GitHub repository. You should file an issue if you:

When you file issues, please be sure to include the following information:

For bug reports, also include:

  1. The source code and configuration information (including .eslintrc and .eslintignore if applicable).
  2. What you did.
  3. What you expected to happen.
  4. What actually happened.

For feature requests, also include:

  1. The problem you want to solve.
  2. Your take on the correct solution to problem.

Please include as much detail as possible to help us properly address your issue. If we need to triage issues and constantly ask people for more detail, that’s time taken away from actually fixing issues. Help us be as efficient as possible by including a lot of detail in your issues.

Note: If you just have a question that won’t necessarily result in a change to ESLint, such as asking how something works or how to contribute, please use the mailing list instead of filing an issue.

Working on Issues

You are welcome to work on any open issue in the issues list. If it’s open, that means we are planning on doing it in the future, and your help is appreciated. Some things to keep in mind:

If you’re going to work on an issue, please add a comment to that issue saying so and indicating when you think you will complete it. It will help us to avoid duplication of effort. Some examples of good comments are:

If an issue has already been claimed by someone, please do not work on it.

If you find you can’t finish the work, then simply add a comment letting people know, for example:

No one will blame you for backing out of an issue if you are unable to complete it. We just want to keep the process moving along as efficiently as possible.

Documentation

We treat documentation the same as we do code, and that means you are welcome to improve upon it. The documentation is located in our repo. All of this documentation gets converted into HTML and pushed to eslint.org with each release.

There are lots of ways to help:

The ESLint project is committed to having great documentation as we believe that quality documentation is ultimately what causes projects to succeed or fail.

Graphic/Web Design

Our site, eslint.org is our public face. It was started by designers and developers who donated their time and energy to getting it off the ground, and in the spirit of open source, we have shared the code in a separate repo.

If you want to help, please check the site issues to see where your help is most needed. In addition, we are always looking to improve our layout, design, and information architecture. Just as with the main ESLint project, you should feel free to file and work on issues.

Important: The documentation (everything under http://eslint.org/docs/) actually resides in the main repo. Changes to that content must be made there. These pages are auto-generated on eslint.org with each release.

Integrations

Part of what makes ESLint useful is the way it integrates into other systems. We have an integrations page that lists out all known integrations. If you have created an integration, please add your information to that page.

Additionally, we are always looking for official integrations to host under the ESLint organization on GitHub. Official integrations are tools that have a high-level quality and are managed by responsible maintainers who are committed to keeping the tool up-to-date and bettering the tool for the good of the ESLint community. If you think your integration qualifies, please contact the mailing list with your information.

Since the code you wrote is your original work, you keep the copyright for it. This is why we ask you to include a copyright in the comments at the beginning of any file you submit, such as:

/**
 * @fileoverview Description of the file
 * @author Your Name
 * @copyright 2014 Your Name. All rights reserved.
 */

The @author field gives you credit for having created the file. The @copyright field indicates that you are the copyright holder for the file.

Your submission may touch other parts of the ESLint code that you did not write. In that case, you are welcome to add a copyright notice to the top of the file if you have done any amount of significant work on the file (we leave it up to you to decide what “significant” means - if you aren’t sure, just ask). You should never change the @author field, but you can add another @copyright field on top of the existing ones, such as:

/**
 * @fileoverview Description of the file
 * @author Author's Name
 * @copyright 2015 Your Name. All rights reserved.
 * @copyright 2014 Author's Name. All rights reserved.
 */

Pull Requests

If you want to contribute to an ESLint repo, please use a GitHub pull request. This is the fastest way for us to evaluate your code and to merge it into the code base. Please don’t file an issue with snippets of code. Doing so means that we need to manually merge the changes in and update any appropriate tests. That decreases the likelihood that your code is going to get included in a timely manner. Please use pull requests.

We want to accept your contribution. Following these guidelines helps to create a patch that we want to accept:

Step 1: Create a new branch

The first step to sending a pull request is to create a new branch in your ESLint fork. Give the branch a descriptive name that describes what it is you’re fixing, such as:

git checkout -b fix-broken-config

Step 2: Make your changes

Make the changes to the code and tests and then commit to your branch. Be sure to follow the commit message conventions.

Commit message summaries must follow this basic format:

Tag: Message (fixes #1234)

The Tag is one of the following:

The message summary should be a one-sentence description of the change. The issue number should be mentioned at the end. If the commit doesn’t completely fix the issue, then use (refs #1234) instead of (fixes #1234).

Here are some good commit message summary examples:

Build: Update Travis to only test Node 0.10 (refs #734)
Fix: Semi rule incorrectly flagging extra semicolon (fixes #840)
Upgrade: Esprima to 1.2, switch to using Esprima comment attachment (fixes #730)

The commit message format is important because these messages are used to create a changelog for each release. The tag and issue number help to create more consistent and useful changelogs.

Step 3: Rebase onto upstream

Before you send the pull request, be sure to rebase onto the upstream source. This ensures your code is running on the latest available code.

git fetch upstream
git rebase upstream/master

Step 4: Run the tests

After rebasing, be sure to run all of the tests once again to make sure nothing broke:

npm test

Step 5: Squash your commits

As mentioned previously, ESLint requires just one commit per pull request. If you have used multiple commits, be sure to squash your commits.

Step 6: Send the pull request

Now you’re ready to send the pull request. Go to your ESLint fork and then follow the GitHub documentation on how to send a pull request.

Following Up

All pull requests are sent through Travis CI to verify that no tests are broken. If the Travis build fails, it will show up on the pull request. We cannot accept any code that fails in Travis, so if this happens, make fixes and update the pull request to trigger another build.

New Rules

If you want to create a new rule, the first step is to file an issue. Make sure the issue includes the following information:

  1. The use case for the rule - what is it trying to prevent or flag? Include code examples.
  2. Whether the rule is trying to prevent an error or is purely stylistic.
  3. Why you believe this rule is generic enough to be included.
  4. Whether the rule should be on or off by default.

To simplify creation of new rules, use ESLint Yeoman generator. It will automatically generate rule, documentation and test files to get you started faster.

Keep in mind that not all rules will be accepted for the main distribution. You may also request that your rule by on by default but we may accept it as off by default.