:toc: macro
:toclevels: 5
:figure-caption!:

= Caliber

This gem provides global link:https://docs.rubocop.org/rubocop[RuboCop] configurations for ensuring
high quality _and_ consistent software development practices.

toc::[]

== Features

* Provides a global configuration for the following code quality gems:
** link:https://docs.rubocop.org/rubocop[RuboCop]
** link:https://github.com/rubocop/rubocop-performance[RuboCop Performance]
** link:https://github.com/rubocop/rubocop-rake[RuboCop Rake]
** link:https://github.com/rubocop/rubocop-rspec[RuboCop RSpec]

== Requirements

* link:https://www.ruby-lang.org[Ruby]
* link:https://github.com/ruby/rake[Rake]
* link:https://rspec.info[RSpec]

== Setup

To install, run:

[source,bash]
----
gem install caliber
----

== Usage

This gem is designed to replace all of your RuboCop setup with only a single reference to this gem.
You'll want to start with your `Gemfile` by adding the following:

[source,ruby]
----
group :code_quality do
  gem "caliber"
end
----

Then, in your `.rubocop.yml`, add the following to the top of the file:

[source,yaml]
----
inherit_gem:
  caliber: config/all.yml
----

That's it!

=== Customization

Should you not want everything that this gem offers, you can customize
the gem further by specifiying what you need:

[source,yaml]
----
inherit_gem:
  caliber:
    - config/ruby.yml
    - config/performance.yml
    - config/rake.yml
    - config/rspec.yml
----

The above is what `config/all.yml` expands to but now you can mix and match how you like for your
needs.

=== Auto-Requires

When Caliber is added to your `Gemfile`, you don't have to require RuboCop because Caliber does that
for you by default. All RuboCop dependencies are also auto-required because they are defined in each
configuration. Here's a full breakdown of how this works:

[source,yaml]
----
inherit_gem:
  caliber:
    - config/all.yml
----

The above will auto-require and load the configurations for following gems:

* RuboCop Performance
* RuboCop Rake
* RuboCop RSpec

When you don't use the default `all.yml` configuration, then behavior changes as follows:

[source,yaml]
----
inherit_gem:
  caliber:
    - config/ruby.yml
----

The above will only load the RuboCop Ruby configuration. Nothing is required since Caliber already
requires the RuboCop gem by default.

[source,yaml]
----
inherit_gem:
  caliber:
    - config/peformance.yml
----

The above will only require the RuboCop Performance gem _and_ load the associated configuration.

[source,yaml]
----
inherit_gem:
  caliber:
    - config/rake.yml
----

The above will only require the RuboCop Rake gem _and_ load the associated configuration.

[source,yaml]
----
inherit_gem:
  caliber:
    - config/rspec.yml
----

The above will only require the RuboCop RSpec gem _and_ load the associated configuration.

=== Import Only

Should you not want to include this gem in your project for some reason, you can directly import the
configuration files supported by this project instead. To do this, you'd need to add the following
to the top of your `.rubocop.yml`:

[source,yaml]
----
inherit_from:
  - https://raw.githubusercontent.com/bkuhlmann/caliber/main/config/all.yml
----

You'll also want to add `.rubocop-https*` to your project's `.gitignore` since imported RuboCop YAML
configurations will be cached locally and you'll not want them checked into your source code
repository.

If importing all configurations from `all.yml` is too much -- and much like you can do with
requiring this gem directly -- you can mix and match what you want to import by defining which
configurations you want to use. For example, the following is what `all.yml` expands too:

[source,yaml]
----
inherit_from:
  - https://raw.githubusercontent.com/bkuhlmann/caliber/main/config/ruby.yml
  - https://raw.githubusercontent.com/bkuhlmann/caliber/main/config/performance.yml
  - https://raw.githubusercontent.com/bkuhlmann/caliber/main/config/rake.yml
  - https://raw.githubusercontent.com/bkuhlmann/caliber/main/config/rspec.yml
----

You can also target a specific version of this gem by swapping out the `main` path in the YAML URLs
listed above with a specific version like `0.0.0`.

Lastly, when using this YAML import approach, you'll not benefit from having all gems you need
required and installed for you. So you'll need to manually require these gems in your `Gemfile`:

* link:https://docs.rubocop.org/rubocop[RuboCop]
* link:https://docs.rubocop.org/rubocop-performance[RuboCop Performance]
* link:https://docs.rubocop.org/rubocop-rspec[RuboCop Rake]
* link:https://docs.rubocop.org/rubocop-rspec[RuboCop RSpec]

== Development

To contribute, run:

[source,bash]
----
git clone https://github.com/bkuhlmann/caliber.git
cd caliber
bin/setup
----

You can also use the IRB console for direct access to all objects:

[source,bash]
----
bin/console
----

=== Check

Use the `bin/check` script -- when upgrading to newer RuboCop gem dependencies -- to check if
duplicate configurations exist. This ensures Caliber configurations don't duplicate effort provided
by RuboCop. The script _only identifies duplicate Caliber configurations which are enabled and have
no other settings_.

When both RuboCop and Caliber are in sync, the following will be output:

....
RUBY: ✓
PERFORMANCE: ✓
RAKE: ✓
RSPEC: ✓
....

When RuboCop has finally enabled cops that Caliber already has enabled, the following will display
as an example:

....
RUBY:
* Lint/BinaryOperatorWithIdenticalOperands
* Lint/ConstantDefinitionInBlock
PERFORMANCE: ✓
RAKE: ✓
RSPEC:
* RSpec/StubbedMock
....

The above can then be used as a checklist to remove from Caliber.

== Tests

To test, run:

[source,bash]
----
bundle exec rake
----

== link:https://www.alchemists.io/policies/license[License]

== link:https://www.alchemists.io/policies/security[Security]

== link:https://www.alchemists.io/policies/code_of_conduct[Code of Conduct]

== link:https://www.alchemists.io/policies/contributions[Contributions]

== link:https://www.alchemists.io/projects/caliber/versions[Versions]

== link:https://www.alchemists.io/community[Community]

== Credits

* Built with link:https://www.alchemists.io/projects/gemsmith[Gemsmith].
* Engineered by link:https://www.alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].