Contributing

Frank van Gemeren edited this page Feb 2, 2016 · 7 revisions

Contributing

One of the great things about open source projects is that anyone can contribute code. CSS Lint has thrived thanks to the contributions of numerous people and we want to encourage everyone to submit their patches freely. To help you in that process, there are several things that you should keep in mind.

Use Pull Requests

If you want to submit code, 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.

Unit Tests

Regardless of the changes you are making, please make sure that your pull request includes appropriate unit tests. If you're submitting a new rule, you can find example unit tests in the tests/rules directory. If you're submitting a change to the core of CSS Lint, update or add to the units tests in the tests/core directory.

Note: The CLI interface currently doesn't have unit tests, we are working on including those. If you're making a change to the CLI, you can either create some new unit tests or do some very thorough testing and report the results in the pull request.

CLI Changes

If you are submitting changes to the CLI, the changes must work in all three environments: Windows Script Host (WSH), Rhino, and Node.js. Please make sure to test your changes in each of these environments before submitting the pull request. The most common reason why CLI patches are declined is because they only work in one or two environments.

Browser and Command Line

With the exception of CLI-specific changes, all other changes must function correctly both in a browser and on the command line. The core of CSS Lint is specifically designed to not know the environment in which it's running so that we can easily use the code in any number of environments. At a minimum, the code has to run on the CSS Lint website and on the command line. Please make sure that your changes work regardless of the environment.

Rules

If you're submitting a new rule, please make sure your pull request includes the following:

  • The rule file
  • A unit test file
  • A description of the rule and why it's important
  • Some documentation about the rule that can be added to our wiki (see Rules for examples)

Keep in mind when submitting a rule that the rule must make sense to be enabled by default. For example: a rule that is only valid for Internet Explorer 6 is probably not one you would want enabled by default. Any rule that is a "sometimes this applies, sometimes it doesn't" type of rule is best left as a custom rule.

Testing

Along with submitting unit tests, please make sure that you have used the built-in testing capabilities in the CSS Lint build system. At a minimum, you should run grunt test. That generates all of the built files and runs all of the unit tests in the project. It also checks for JavaScript stylistic issues using JSHint. No pull requests will be accepted if either JSHint or any unit test doesn't pass.

Contributor License Agreement

To prevent, and solve, potential legal issues, we've provided a short Contributor License Agreement in the file CONTRIBUTING.md. Please make sure your contribution is following those rules.