Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/bkuhlmann/caliber

A global, high quality, and constantly updated RuboCop configuration.
https://github.com/bkuhlmann/caliber

Last synced: 2 days ago
JSON representation

A global, high quality, and constantly updated RuboCop configuration.

Awesome Lists containing this project

README 

        
:toc: macro

:toclevels: 5

:figure-caption!:



:rubocop_capybara_link: link:https://docs.rubocop.org/rubocop-capybara[RuboCop Capybara]

:rubocop_disable_syntax_link: link:https://github.com/fatkodima/rubocop-disable_syntax[RuboCop Disable Syntax]

:rubocop_link: link:https://docs.rubocop.org/rubocop[RuboCop]

:rubocop_packaging_link: link:https://docs.rubocop.org/rubocop-packaging[RuboCop Packaging]

:rubocop_performance_link: link:https://docs.rubocop.org/rubocop-performance[RuboCop Performance]

:rubocop_rake_link: link:https://docs.rubocop.org/rubocop-rspec[RuboCop Rake]

:rubocop_rspec_link: link:https://docs.rubocop.org/rubocop-rspec[RuboCop RSpec]

:rubocop_thread_safety_link: link:https://github.com/rubocop/rubocop-thread_safety[RuboCop Thread Safety]

:xdg_configuration_link: link:https://alchemists.io/articles/xdg_base_directory_specification[XDG Base Directory Specification]



= Caliber



This gem provides global link:https://docs.rubocop.org/rubocop[RuboCop] configurations for ensuring

high quality _and consistent_ software development practices.



_Due to the ever changing nature of the RuboCop ecosystem -- and the fact you can fall behind quickly -- this gem takes an aggressive approach to staying atop the latest changes. This also means this gem might never reach Version 1.0.0 because new -- often breaking -- changes are being introduced in each minor release. That said, if you always want to keep pace with recent changes -- *because you know how costly technical debt is* -- then this gem has you covered. 🎉_



toc::[]



== Features



* Provides a global configuration for the following code quality gems:

** {rubocop_link}

** {rubocop_capybara_link}

** {rubocop_disable_syntax_link}

** {rubocop_packaging_link}

** {rubocop_performance_link}

** {rubocop_thread_safety_link}

** {rubocop_rake_link}

** {rubocop_rspec_link}



== Requirements



* link:https://www.ruby-lang.org[Ruby]



== Setup



To install _with_ security, run:



[source,bash]

----

# 💡 Skip this line if you already have the public certificate installed.

gem cert --add <(curl --compressed --location https://alchemists.io/gems.pem)

gem install caliber --trust-policy HighSecurity

----



To install _without_ security, run:



[source,bash]

----

gem install caliber

----



You can also add the gem directly to your project:



[source,bash]

----

bundle add 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 :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



You can customize the gem by specifying what you need:



[source,yaml]

----

inherit_gem:

  caliber:

    - config/ruby.yml

    - config/capybara.yml

    - config/disable_syntax.yml

    - config/packaging.yml

    - config/performance.yml

    - config/thread.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 specific needs.



=== Requirements



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 automatically 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 require and load the configurations for following gems:



* {rubocop_link}

* {rubocop_capybara_link}

* {rubocop_disable_syntax_link}

* {rubocop_packaging_link}

* {rubocop_performance_link}

* {rubocop_thread_safety_link}

* {rubocop_rake_link}

* {rubocop_rspec_link}



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



*Ruby*



[source,yaml]

----

inherit_gem:

  caliber:

    - config/ruby.yml

----



The above will only load the {rubocop_link} Ruby configuration. No further requirements are necessary since Caliber already requires the RuboCop gem by default.



*Capybara*



[source,yaml]

----

inherit_gem:

  caliber:

    - config/capybara.yml

----



The above will only require the {rubocop_capybara_link} gem _and_ load the associated configuration.



💡 This is a dependency of {rubocop_rspec_link} so doesn't need to be directly required if already requiring {rubocop_rspec_link}.



*Disable Syntax*



[source,yaml]

----

inherit_gem:

  caliber:

    - config/disable_syntax.yml

----



The above will only require the {rubocop_disable_syntax_link} gem _and_ load the associated configuration.



*Packaging*



[source,yaml]

----

inherit_gem:

  caliber:

    - config/packaging.yml

----



The above will only require the {rubocop_packaging_link} gem _and_ load the associated configuration.



*Performance*



[source,yaml]

----

inherit_gem:

  caliber:

    - config/peformance.yml

----



The above will only require the {rubocop_performance_link} gem _and_ load the associated configuration.



*Thread Safety*



[source,yaml]

----

inherit_gem:

  caliber:

    - config/thread.yml

----



The above will only require the {rubocop_thread_safety_link} gem _and_ load the associated configuration.



*Rake*



[source,yaml]

----

inherit_gem:

  caliber:

    - config/rake.yml

----



The above will only require the {rubocop_rake_link} gem _and_ load the associated configuration.



*RSpec*



[source,yaml]

----

inherit_gem:

  caliber:

    - config/rspec.yml

----



The above will only require the {rubocop_rspec_link} gem _and_ load the associated configuration.



=== Inheritance



Should you not want to include this gem in your project for some reason, you can directly inherit the configuration files supported by this project instead. To do this, you'll 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/capybara.yml

  - https://raw.githubusercontent.com/bkuhlmann/caliber/main/config/disable_syntax.yml

  - https://raw.githubusercontent.com/bkuhlmann/caliber/main/config/packaging.yml

  - https://raw.githubusercontent.com/bkuhlmann/caliber/main/config/performance.yml

  - https://raw.githubusercontent.com/bkuhlmann/caliber/main/config/thread.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`:



* {rubocop_link}

* {rubocop_capybara_link}

* {rubocop_disable_syntax_link}

* {rubocop_packaging_link}

* {rubocop_performance_link}

* {rubocop_thread_safety_link}

* {rubocop_rake_link}

* {rubocop_rspec_link}



=== Coexistence



In situations where you'd like to use Caliber alongside additional RuboCop gems, you only need to add the new gems to your `Gemfile` and then require them within your `.rubocop.yml`. For example, let's say you wanted to use both the Caliber and link:https://github.com/rubocop/rubocop-md[RuboCop Markdown] gems together. Here is how you can use both by updating your `.rubocop.yml` (assuming your `Gemfile` was updated as well):



[source,yaml]

----

inherit_gem:

  caliber: config/all.yml



require:

  - rubocop-md

----



Adding additional RuboCop gems only requires adding them to your YAML configuration.



=== Command Line Interface (CLI)



⚠️ This is experimental but might be of interest to anyone using RuboCop's local {xdg_configuration_link} (highly recommend).



At the moment, RuboCop doesn't have native functionality for handling these updates and this CLI is one solution to that problem (see this link:https://github.com/rubocop/rubocop/issues/12729[issue] for details). So this CLI automates the updating of outstanding issues you have not resolved for your RuboCop configuration (i.e. `.rubocop_todo.yml`) and is handy when you've fixed issues and want to update your configuration to reflect these changes. The CLI assumes you are using the following structure:



....

.config/rubocop/config.yml

.config/rubocop/issues.yml

....



...and that you have this line in `.config/rubocop/config.yml`:



[source,yaml]

----

inherit_from: issues.yml

----



Assuming the above is true, you can run the `caliber` CLI and follow the prompts for either updating your outstanding issues or exiting. Upon competition, the CLI will update your `.config/rubocop/issues.yml` so you can commit these updates/changes to your repository.



== Development



To contribute, run:



[source,bash]

----

git clone https://github.com/bkuhlmann/caliber

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: ✓

CAPYBARA: ✓

DISABLE_SYNTAX: ✓

PACKAGING: ✓

PERFORMANCE: ✓

THREAD: ✓

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

CAPYBARA: ✓

DISABLE_SYNTAX: ✓

PACKAGING: ✓

PERFORMANCE: ✓

THREAD: ✓

RAKE: ✓

RSPEC:

* RSpec/StubbedMock

....



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



== Tests



To test, run:



[source,bash]

----

bin/rake

----



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



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



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



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



== link:https://alchemists.io/policies/developer_certificate_of_origin[Developer Certificate of Origin]



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



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



== Credits



* Built with link:https://alchemists.io/projects/gemsmith[Gemsmith].

* Engineered by link:https://alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].