Lint Review

Lint Review helps automate a tedious part of code review - enforcing coding standards. By using the github API Lint Review runs a repository's configured linters and updates pull requests with line comments where lint errors would be introduced.

Lint Review requires:

• Python 2.7 (It will probably work in 2.6, but I've only tested 2.7)
• RabbitMQ (or any other Message broker that is compatible with Celery)
• A publically addressable hostname/IP that either github or your github:enterprise can reach.
• A github account with read/write access to the repositories you want linted. This account is used to post comments on pull reviews.

Lint Review runs as two processes. A web process handles accepting webhooks from github, and a celery process handles cloning repositories and running lint tools. You'll also need to have rabbitmq-server running.

Installation

You install Lint Review by cloning the repository and installing dependecies, or by using docker. If you are not using docker, it is recommended that you use virtualenv to save shaving yaks down the road.

git clone git://github.com/markstory/lint-review.git
cd lint-review
virtualenv env
source env/bin/activate
pip install .

In addtion to installing the dependencies for lint-review you will also need to install the various lint tools you want to use. Lint-review requires that lint tools be installed relative to the source code. pep8 and flake8 will be installed as dependencies for lint-review, but any other tools will need to be installed using their respective installers. To install all the tools run the following:

# Install ruby tools
bundle install --path ./bundle

# Install javascript tools.
npm install

# Install PHP tools
php composer.phar install

Once the dependencies are installed you should configure the repositories you want to review.

Using Docker

To use docker, you'll need to install both docker, docker-compose and possibly docker toolbox depending on your operating system. Once you have the docker installed, you can boot up lint-review into docker using:

docker build --tag=lintreview_image .
docker-compose up -d broker worker web

Edit docker-composer.yml and customise your configuration by setting keys under environment for the web and worker processes. For the most basic installation you'll need to set at least GITHUB_USERNAME and GITHUB_PASSWORD (or GITHUB_OAUTH_TOKEN), and LINTREVIEW_SERVER_NAME.

Lint Review Configuration

Lint review is configured through a settings file. Both the web app and celery process share the same configuration file, so configuration is easier to manage and share.

• Copy the settings.sample.py to settings.py

• Edit the required configuration options, or set the correct environment variables.

• Set the LINTREVIEW_SETTINGS environment variable to the path of your configuration files. In *nix system this can be done via:

  export LINTREVIEW_SETTINGS='/path/to/settings.py'
  

• You can skip setting LINTREVIEW_SETTINGS if you're running lintreview from a directory containing your settings.py file.

You can also have per install configuration files by defining the LINTRC_DEFAULTS config option in your settings file. This file should be a .lintrc config file. It will be merged with each projects .lintrc before running tools. This gives you an easy way to have global configuration for tools.

Setting up Repositories

Once you've configured the server processes, it is time to setup some repositories to be checked.

Installing github hooks

Before Lint Review can check pull requests on a repository webhooks will need to be installed. You can install webhooks by running the built-in command line tool:

source env/bin/activate
lintreview register mark awesome-stuff

Or, if you're using Docker:

docker-compose run web lintreview register mark awesome-stuff

The above register webhooks for the given user & repository. You can use the --user and --password options to provide the repository admin credentials if the user lint-review runs as does not have admin access to the repository. You can also use the cli tool to remove webhooks:

source env/bin/activate
lintreview unregister mark awesome-stuff

Warning The current web server name will be registered with github. Make sure it is configured properly before registering hooks, or you'll need to remove any registered hooks and start over.

.lintrc files

Lint Review use hidden ini files to configure the tools used on each project. The .lintrc file defines the various linting tools and any arguments for each one. Lint tools must be tools Lint Review knows about. See lint tools for available tools. A sample .lintrc file would look like.

[files]
ignore = generated/*
    vendor/*

[tools]
linters = pep8, jshint

[tool_pep8]
ignore = W2,E401

[tool_jshint]
config = path/to/jshint.json

The [tools] section is required, and linters should be a list of linters your project uses. Each tool can also have a section prefixed with tool_ to define additional configuration options for each tool. The documentation for each tool outlines which options are supported.

The [files] section is optional and allows you to define ignore patterns. These patterns are used to find and exclude files when doing a review. Ignore patterns use glob expressions to find files. The patterns start at the reviewed repository root. If you need to ignore mulitple patterns separate them with new lines.

Running Lint Review

After setting up configuration you'll need to start up both processes:

source env/bin/activate
gunicorn -c settings.py lintreview.web:app
celery -A lintreview.tasks worker

Now when ever a pull request is opened or updated for a registered repository new jobs will be spun up and lint will be checked and commented on.

Lint tools

Python:

Flake8

Uses the flake8 module to check code.

Options

• ignore Set which pep8 error codes you wish to ignore.
• exclude Exclude files or directories which match these comma separated patterns (default: .svn, CVS, .bzr, .hg, .git)
• filename When parsing directories, only check filenames matching these comma separated patterns (default: *.py)
• select Select errors and warnings (e.g. E,W6)
• max-line-length Set maximum allowed line length (default: 79)
• format Set the error format [default|pylint|]
• max-complexity McCabe complexity threshold
• snippet Interacts with flake8-snippets allowing you to trigger errors on specific snippets you want to disallow.

These options are passed into flake8 as cli options.

pep8

Uses the pep8 module to check code.

Options

• ignore Set which pep8 error codes you wish to ignore.

PHP

PHPCS

Uses the phpcs PEAR library to do style checks on PHP, Javascript and or CSS files.

Options

• standard The coding standard to use. By default the PSR2 standard is used. You can use any of the built-in standards or provide your own inside your project directory.
• extensions The extensions to check. By default only .php files will be checked.
• tab_width The number of spaces to convert tabs into, this is useful for projects using tabs for indentation.

Javascript:

JSCS

Uses the JSCS npm module to check javascript files. Before you can use this linter you'll need to install nodejs and the jscs npm package:

cd path/to/lintreview
npm install jscs

Options

• config Provide a path to the json config file for JSCS.
• preset Set which JSCS preset you want to use. Unused if config is set.

JSHint

Uses the jshint npm module to check javascript files. Before you can use this linter you'll need to install nodejs and the jshint npm package:

cd path/to/lintreview
npm install jshint

Options

• config Provide a path to the json config file for jshint.

ESLint

Uses the eslint npm module to check javascript files. Before you can use this linter you'll need to install the eslint npm package:

cd path/to/lintreview
npm install eslint

Options

• config Provide a path to the json config file for eslint.

CSS:

CSSLint

Uses the csslint npm module to check css files. Before you can use this linter you'll need to install nodejs and the csslint npm package:

cd path/to/lintreview
npm install csslint

Both warnings and errors will be turned into code review comments. If you don't want code review comments for specific rules, you should ignore them.

Options

• ignore A comma separated list of rule ids to ignore.

Ruby:

RuboCop

Uses the rubocop gem to check ruby files. You'll need to install it to use it:

gem install rubocop

Options

• display_cop_names Set to true to pass display cop names in offense messages.

.rubocop.yml files will be respected, as described here.

Puppet:

puppet-lint

Uses the puppet-lint gem to check puppet manifests against the puppetlabs style guide.

You'll need to install it to use it:

gem install puppet-lint

Options

No options. .puppet-lintrc files will be respected, to allow each project to disable checks. A list of checks can be found by running "puppet-lint --help"

Chef:

Foodcritic

Uses the Foodcritic gem to check Chef files. You'll need to install Foodcritic:

gem install foodcritic

Options

• path If your cookbooks aren't stored in the root, use this to set the path that foodcritic runs against. Example: path = cookbooks