README.md in quality-27.4.0 vs README.md in quality-28.0.0
- old
+ new
@@ -9,11 +9,13 @@
different analysis tools and makes sure your numbers don't get any
worse over time.
## Why
-See [this post](http://blog.apiology.cc/2014/06/scalable-quality-part-1.html) or [these slides](https://docs.google.com/presentation/d/1Op4FH34-enm8luEIuAAVLkuAJ-sB4LKaMm57RJzvfeI/edit#slide) for more information on the problem the quality gem solves.
+See [this post](http://blog.apiology.cc/2014/06/scalable-quality-part-1.html)
+or [these slides](https://docs.google.com/presentation/d/1Op4FH34-enm8luEIuAAVLkuAJ-sB4LKaMm57RJzvfeI/edit#slide)
+for more information on the problem the quality gem solves.
### Tools
Quality makes use of the following other tools, which do the actual checking:
@@ -32,158 +34,142 @@
* [reek](https://github.com/troessner/reek)
* [rubocop](https://github.com/bbatsov/rubocop)
## How to use - using Docker
-These basic steps assume you have a working Docker installation.
-
```
docker run -v `pwd`:/usr/app apiology/quality:latest
```
If you'd like to customize, you can link in your own Rakefile like this:
```
docker run -v `pwd`:/usr/app -v `pwd`/Rakefile.quality:/usr/quality/Rakefile apiology/quality:latest
```
-The default 'latest' tag contains the Ruby tools in a relatively small image. You can also get additional tools (see `Dockerfile.jumbo` in this directory) by using the tag `jumbo-`(version) (e.g., jumbo-latest, jumbo-x.y.z, etc)
+The default 'latest' tag contains the Ruby tools in a relatively small
+image. You can also get additional tools (see `Rockerfile` in
+this directory) by using the tag `jumbo-`(version) (e.g.,
+jumbo-latest, jumbo-x.y.z, etc)
## How to use - as part of a Ruby-based Rakefile
```bash
-$ pip install pep8 flake8
-$ brew install cmake icu4c shellcheck scalastyle # OS X
-$ gem install quality
+pip install pep8 flake8
+brew install cmake icu4c shellcheck scalastyle # OS X
+gem install quality
```
or in your Gemfile:
```ruby
group :development do
gem 'quality'
end
```
+
and then:
```bash
-$ bundle install
+bundle install
```
Once you have the gem, configure your Rakefile like this:
```ruby
require 'quality/rake/task'
Quality::Rake::Task.new
```
+If you're using Rails, you must check your environment in your
+Rakefile.
+
+```ruby
+if Rails.env.development?
+ require 'quality/rake/task'
+
+ Quality::Rake::Task.new
+end
+```
+
Then run:
```bash
-$ rake quality
+rake quality
```
If you want to ratchet up the quality and force yourself to improve
code, run:
```bash
-$ rake ratchet
+rake ratchet
```
## Configuration options
-```ruby
-Quality::Rake::Task.new do |t|
- # Name of quality task.
- # Defaults to :quality.
- t.quality_name = 'quality'
+See [CONFIGURATION.md](CONFIGURATION.md)
- # Name of ratchet task.
- # Defaults to :ratchet.
- t.ratchet_name = 'ratchet'
-
- #
- # Set minimum values to ratchet to.
- #
- # Defaults to { bigfiles: 300 }
- #
- t.minimum_threshold = { bigfiles: 300 }
-
- # Array of strings describing tools to be skipped--e.g., ["cane"]
- #
- # Defaults to []
- t.skip_tools = []
-
- # Log command executation
- #
- # Defaults to false
- t.verbose = false
-
- # Relative path to output directory where *_high_water_mark
- # files will be read/written
- #
- # Defaults to 'metrics'
- t.output_dir = 'metrics'
-
- # Pipe-separated regexp string describing what to look for in
- # files as 'todo'-like 'punchlist' comments.
- #
- # Defaults to 'XXX|TODO|FIXME|OPTIMIZE|HACK|REVIEW|LATER|FIXIT'
- t.punchlist_regexp = 'XXX|TODO|FIXME|OPTIMIZE|HACK|REVIEW|LATER|FIXIT'
-
- # Exclude the specified list of files--defaults to ['db/schema.rb']
- t.exclude_files = ['lib/whatever/imported_file.rb',
- 'lib/vendor/someone_else_fault.rb']
-
- # Alternately, express it as a glob:
-
- # Exclude the specified list of files
- t.source_files_exclude_glob =
- '{lib/whatever/imported_file.rb,lib/vendor/**/*.rb}'
-
- #
- # For configuration on classifying files as the correct language,
- # see https://github.com/github/linguist
- #
-end
-```
-
## Vendored files
-Quality uses GitHub's [linguist](https://github.com/github/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](https://github.com/github/linguist#overrides) to use the `gitattributes` file to mark files as vendored, at which point Quality will not try to analyze them.
-
+Quality uses GitHub's [linguist](https://github.com/github/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](https://github.com/github/linguist#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.
+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](https://github.com/brianmario/charlock_holmes/issues/117)
+failures in charlock_holmes. To work around, if you are
+using
+[Homebrew](https://github.com/brianmario/charlock_holmes#homebrew):
+
+```sh
+bundle config build.charlock_holmes --with-cxxflags=-std=c++11 --with-icu-dir=/usr/local/opt/icu4c
+```
+
## Caveats
-Quality uses [semantic versioning](http://semver.org/)--any incompatible changes (including new tools being added) will come out as major number updates.
+Quality uses [semantic versioning](http://semver.org/)--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.
+
+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.
## Contributing
* Fork the repo
* Create a feature branch
* Submit a github pull request
-Many thanks to all contributors, especially [@andyw8](https://github.com/andyw8), who has contributed some great improvements.
-
-### Learn More
-
-* Browse the code or install the latest development version from [https://github.com/apiology/quality/tree](https://github.com/apiology/quality/tree)
+Many thanks to all contributors, especially [@andyw8](https://github.com/andyw8),
+who has contributed some great improvements.
## License
Licensed under the MIT license.