Contributing

This page explains how the CoffeeLint codebase is developed: setting up a checkout, running the tests, adding a rule, and the release process the maintainers used.

Note: The repository's README states that CoffeeLint is no longer maintained. Pull requests to the original repository are unlikely to be reviewed. The information below is still useful if you maintain a fork or want to understand how the project was built.

Development Setup

git clone https://github.com/clutchski/coffeelint.git
cd coffeelint
npm install

npm install also runs the package's install script, which compiles src/ into lib/ if lib/commandline.js does not exist yet.

While developing, you can delete lib/: bin/coffeelint then runs the CoffeeScript sources in src/ directly, compiling them on the fly, so every change takes effect immediately (handy when an editor plugin calls coffeelint as you type).

npm Scripts

Command What it does
npm run compile Runs cake compile: builds the Browserify bundle lib/coffeelint.js and compiles the command-line modules and reporters.
npm test Compiles (pretest), runs every test in test/*.coffee and test/*.litcoffee with Vows, then lints the repository itself (posttest).
npm run testrule <test file> Compiles, then runs a single test file, for example npm run testrule test/test_no_tabs.coffee.
npm run lint Compiles and runs ./bin/coffeelint . on the repository.
npm run lint-csv / npm run lint-jslint The same, with the deprecated --csv or --jslint output flags.

The scripts call ./vowsrunner.js and ./bin/coffeelint directly, which assumes a POSIX-style shell.

The repository lints itself with its own coffeelint.json (four-space indentation, spaces around operators and after commas, { a: b } brace spacing, and more), so new code must follow that style for npm test to pass.

Adding a Rule

The project's contributor guide lists these steps:

  1. Fork the repository.
  2. Run npm install to get the dependencies.
  3. Create the rule in a single file, src/rules/your_rule_here.coffee, using the existing rules as a guide. To inspect the tokens and AST of a snippet, use clfiddle.
  4. Add a test file to the test directory.
  5. Register the rule in src/coffeelint.coffee (rules are listed explicitly so Browserify includes them).
  6. Run your test with npm run testrule test/your_test_here.coffee.
  7. Run the whole suite with npm test.
  8. Check that the rule's documentation renders correctly (see below).
  9. Squash your commits into one.
  10. Open a pull request.

Conventions for New Rules

  • Default to warn (or ignore). Users expect upgrades not to break their builds. Use error only for rules that demonstrably prevent bugs; no_debugger is cited as the model of a rule that earns a non-ignore default.
  • Name by purpose. no_foo for rules that catch specific constructs, foo for rules that enforce formatting.
  • Document in description. The rule's description (HTML allowed) is what the project website renders as the rule's documentation.

The rule API is described in Writing Custom Rules.

Writing Tests

Tests use Vows. Each test file describes a batch of topics (source snippets) and assertions on the result of coffeelint.lint:

path = require 'path'
vows = require 'vows'
assert = require 'assert'
coffeelint = require path.join('..', 'lib', 'coffeelint')

vows.describe('no_forbidden_names').addBatch({

    'Forbidden names':
        topic: () ->
            '''
            voldemort = 1
            harry = 2
            '''

        'are reported': (source) ->
            config = { no_forbidden_names: { level: 'error' } }
            errors = coffeelint.lint(source, config)
            assert.equal(errors.length, 1)
            assert.equal(errors[0].lineNumber, 1)

}).export(module)

Tests load the compiled lib/coffeelint, which is why every test command compiles first.

Updating the Rule Documentation

The website documentation lived on the gh-pages branch and was generated from each rule's description. To preview a new rule's documentation:

  1. Check out the branch with your rule and run npm run compile.
  2. Check out gh-pages (git checkout origin/gh-pages).
  3. Copy the bundle: cp lib/coffeelint.js js/coffeelint.js.
  4. Regenerate the HTML with rake updatehtml (requires Rake).
  5. Open index.html in a browser and check the rule's entry.

Editor and build-tool plugins were listed on the site via pull requests against index-bottom.html on the same branch.

Release Process

The maintainers' release checklist, useful for forks:

  1. Review changes since the last tag to decide between a minor and a patch release. CoffeeLint follows semantic versioning; adding a rule, even one that is off by default, is at least a minor release.
  2. Tag with npm version <major|minor|patch>.
  3. Write the changelog on the gh-pages branch (in index-bottom.html), leaving out internal changes that do not matter to users.
  4. Update the website's bundled copy with rake update, which prints the commands to copy and paste.
  5. Push master, gh-pages, and the new tag.
  6. Publish to npm. The prepublish script removes browserify, coffeeify, and the install script from package.json (they are only needed for Git installs) and compiles the code; postpublish restores package.json. The maintainers ran these steps manually to double-check:
npm run prepublish
git diff
npm publish
git checkout package.json

Code of the Project