Integrating or upgrading makandra-rubocop

Updated . Posted . Visible to the public.


Most of the time it is a tedious task to apply a code style guide to an existing code base as there are likely to be a lot of conflicts. At makandra we are using makandra-rubocop to have code style checks. Here is some advice on how to add makandra-rubocop efficiently.


RubyMine by default has a Rubocop inspection with rules that we don't always agree with. We recommend replacing this with makandra-rubocop or disabling the inspection.

1. Adding the gem to an existing code base

Follow the instructions in the README Show snapshot . Most likely you want:

  • to add the Ruby, Rails and RSpec cops
  • to include the unit test

2. Report all existing offenses and exclude them initially

To start your Rubocop integration it is useful to split your commits. This makes it easier to bisect breaking changes and commit faster to the master, so you and your colleagues don't have a big overhead with merge conflicts.

  1. Get all existing offenses
bundle exec rubocop --parallel --format offenses

541/541 files

383  Layout/ArrayAlignment
352  Layout/ArgumentAlignment
735  Total
  1. Initially exclude them all in your .rubocop.yml:
    - config/default.yml
    - config/ext/rspec.yml
    - config/ext/rails.yml

# 383
  Enabled: false

# 352
  Enabled: false

You can also run bundle exec rubocop --auto-gen-config to create a file that excludes all current violations.

Your tests (including the Rubocop spec) should now all be green. Commit theses changes and consider whether you want to keep all these changes in a feature branch or merge them regularly to the master branch, so you and your colleagues don't have a big overhead with merge conflicts. And no new offenses are added in the meantime you are working on the Rubocop integration

3. Fixing each cop per commit

Now you can start fixing each cop. Remove the disabled cop from your .rubocop.yml and check all offenses. You might want to use the safe (--autocorrect or -a) and unsafe auto correct (--autocorrect-all or -A) option:

bundle exec rubocop --autocorrect # safe auto correct
bundle exec rubocop --autocorrect-all # safe and unsafe auto correct

Afterwards check if your tests are still green. Then commit the change. Continue with this step until all disabled steps from your .rubocop.yml are gone. Consider to merge your changes in a regularly basis to the master branch. Sometimes you might want to keep a cop disabled or reconfigure it depending on the project setup.

4. Finish the integration or upgrade

After you are finished you most likely have a long commit list:

Enable Layout/ArrayAlignment
Enable Layout/ArgumentAlignmen
Add makandra-rubocop without any offenses

Further helpful actions

  • Correcting a single Cop

    $ rubocop --autocorrect --only Style/StringLiterals
  • Correcting an entire category

    $ rubocop --autocorrect --only Style
  • Disabling a cop in source code (as described in the docs Show snapshot )

    • inline
    var1 = 'hello' # rubocop:disable Naming/VariableNumber (here you can add a comment why)
    • multiline
    # rubocop:disable Naming/VariableNumber (here you can add a comment why)
    var1 = 'hello'
    var2 = 'Hello'
    # rubocop:enable Naming/VariableNumber
  • Disabling a cop (in .rubocop.yml)

      Enabled: false
  • Excluding or including some directories in .rubocop.yml

        - 'spec/**/*'
        - 'spec/bin/**/*'
Daniel Straßner
Last edit
Maximilian Berger
Source code in this card is licensed under the MIT License.
Posted by Daniel Straßner to makandra dev (2019-10-14 08:10)