Quality -- code quality ratchet for Ruby

Overview

Quality is a tool that runs quality checks on code in git repos using different analysis tools and makes sure your numbers don't get any worse over time.

Why

See this post or these slides for more information on the problem the quality gem solves.

Tools

Quality makes use of the following other tools, which do the actual checking:

How to use - using Docker

See DOCKER.md for info.

How to use - as part of a Ruby-based Rakefile

pip install flake8
brew install cmake icu4c shellcheck scalastyle # macOS
gem install quality

or in your Gemfile:

group :development do
  gem 'quality'
end

and then:

bundle install

Once you have the gem, configure your Rakefile like this:

require 'quality/rake/task'

Quality::Rake::Task.new

If you're using Rails, you must check your environment in your Rakefile.

if Rails.env.development?
  require 'quality/rake/task'

  Quality::Rake::Task.new
end

Then run:

rake quality

If you want to ratchet up the quality and force yourself to improve code, run:

rake ratchet

Configuration options

See CONFIGURATION.md

Pronto

To help better understand which warnings came from your current set of changes, consider using Pronto, which provides incremental reporting from different quality tools, and can add comments directly to PR reviews. You can see an example in this project's Rakefile

Vendored files

Quality uses GitHub's linguist gem to find and classify source files to analyze. In addition to the exclude_files and source_files_exclude_glob options in Quality, you can refer to Linguists's documentation on overrides to use the gitattributes file to mark files as vendored, at which point Quality will not try to analyze them.

Code coverage

You can pull a similar trick with code coverage using SimpleCov in Ruby--put 'simplecov' in your Gemfile, and add the code below into your test_helper.rb or spec_helper.rb.

require 'simplecov'
SimpleCov.start
SimpleCov.refuse_coverage_drop

After your first run, check in your coverage/.last_run.json.

Build

On OS X, you may see build failures in charlock_holmes. To work around, if you are using Homebrew:

bundle config build.charlock_holmes --with-cxxflags=-std=c++11 --with-icu-dir=/usr/local/opt/icu4c

Caveats

Quality uses semantic versioning--any incompatible changes (including new tools being added) will come out as major number updates.

This includes RuboCop upgrades - the quality gem locks in a specific minor version of RuboCop to avoid your metrics being bumped and breaking your build. This lock affects both the Docker-based quality gem (helping to ensure build stability for floating major versions) as well as the gem when included directly in your project's gems.

Expect your build to break on major upgrades if you use RuboCop.

Supported Ruby Versions

Tested against Ruby >=2.2--does not support Ruby 1.9.x or JRuby.

Contributions

This project, as with all others, rests on the shoulders of a broad ecosystem supported by many volunteers doing thankless work, along with specific contributors.

In particular I'd like to call out:

Audrey Roy Greenfeld for the cookiecutter tool and associated examples, which keep my many projects building with shared boilerplate with a minimum of fuss.