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.
If you’d like to work on a pull request and you’ve never submitted code before, follow these steps:
- Sign our Contributor License Agreement.
- Set up a development environment.
- Ensure there’s an issue that describes what you’re doing. You can create a new issue or just indicate you’re working on an existing issue.
- Exception: documentation-only changes do not require an issue.
After that, you’re ready to start working on code.
Working with Code
The process of submitting a pull request is fairly straightforward and generally follows the same pattern each time:
- Create a new branch
- Make your changes
- Rebase onto upstream
- Run the tests
- Squash your commits
- Double check your submission
- Submit the pull request
Details about each step are found below.
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 issue1234
You should do all of your development for the issue in this branch.
Note: Do not combine fixes for multiple issues into one branch. Use a separate branch for each issue you’re working on.
Step 2: Make your changes
Make the changes to the code and tests, following the code conventions as you go. Once you have finished, commit the changes to your branch:
$ git add -A $ git commit
Our commit message format is as follows:
Tag: Short description (fixes #1234) Longer description here if necessary
The first line of the commit message (the summary) must have a specific format. This format is checked by our build tools.
Tag is one of the following:
Fix- for a bug fix.
Update- for a backwards-compatible enhancement or a change to a rule that increases the number of reported problems.
New- implemented a new feature.
Breaking- for a backwards-incompatible enhancement or feature.
Docs- changes to documentation only.
Build- changes to build process only.
Upgrade- for a dependency upgrade.
Chore- for refactoring, adding tests, etc. (anything that isn’t user-facing).
Use the labels of the issue you are working on to determine the best tag.
The message summary should be a one-sentence description of the change, and it must be 72 characters in length or shorter. The issue number should be mentioned at the end. If the commit doesn’t completely fix the issue, then use
(refs #1234) instead of
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:
Step 5: Squash your commits
ESLint requires just one commit per pull request. If you have used multiple commits, be sure to squash your commits.
Step 6: Double check your submission
With your code ready to go, this is a good time to double-check your submission to make sure it follows our conventions. Here are the things to check:
npm run check-committo double-check that your commit is formatted correctly.
- Make sure there is an issue for any pull request you send.
- The only exception is for documentation changes.
- The pull request must have a description. The description should explain what you did and how its effects can be seen.
- The commit message is properly formatted.
- The change introduces no functional regression. Be sure to run
npm testto verify your changes before submitting a pull request.
- Make separate pull requests for unrelated changes. Large pull requests with multiple unrelated changes may be closed without merging.
- All changes must be accompanied by tests, even if the feature you’re working on previously had no tests.
- All user-facing changes must be accompanied by appropriate documentation.
- Only one commit is allowed per pull request. If you have multiple commits, you’ll be asked to squash them.
- Follow the Code Conventions.
Step 7: 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.
Once your pull request is sent, it’s time for the team to review it. As such, please make sure to:
- Monitor the status of the Travis CI build for your pull request. If it fails, please investigate why. We cannot merge pull requests that fail Travis for any reason.
- Respond to comments left on the pull request from team members. Remember, we want to help you land your code, so please be receptive to our feedback.
- We may ask you to make changes, rebase, or squash your commits.
Updating the Commit Message
If your commit message is in the incorrect format, you’ll be asked to update it. You can do so via:
$ git commit --amend
This will open up your editor so you can make changes. After that, you’ll need to do a forced push to your branch:
$ git push origin issue1234 -f
Updating the Code
If we ask you to make code changes, there’s no need to close the pull request and create a new one. Just go back to the branch on your fork and make your changes. Then, when you’re ready, you can add your changes into the branch:
$ git add -A $ git commit --amend --no-edit $ git push origin issue1234 -f
This snippets adds all your new changes, then amends the previous commit with them. The
--no-edit means you don’t want to edit the commit message; you can omit that option if you need to make commit message changes as well.
If your code is out-of-date, we might ask you to rebase. That means we want you to apply your changes on top of the latest upstream code. You can do so via:
$ git fetch upstream $ git rebase upstream/master
You might find that there are merge conflicts when you attempt to rebase. Please resolve the conflicts and then do a forced push to your branch:
$ git push origin issue1234 -f
If you have more than one commit on your pull request, we’ll ask you to squash your commits. Once your commits are squashed, you can do a forced push to update your branch:
$ git push origin issue1234 -f