Integrating or upgrading makandra-rubocop

Introduction

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.

Note

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 archive.org 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

Copybundle exec rubocop --parallel --format offenses

541/541 files

383  Layout/ArrayAlignment
352  Layout/ArgumentAlignment
--
735  Total

2. Initially exclude them all in your .rubocop.yml:

Copyinherit_gem:
  makandra-rubocop:
    - config/default.yml
    - config/ext/rspec.yml
    - config/ext/rails.yml

# 383
Layout/ArrayAlignment:
  Enabled: false

# 352
Layout/ArgumentAlignment:
  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:

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

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

Further helpful actions

• Correcting a single Cop

  Copy$ rubocop --autocorrect --only Style/StringLiterals
  

• Correcting an entire category

  Copy$ rubocop --autocorrect --only Style
  

• Disabling a cop in source code (as described in the docs Show archive.org snapshot )

  • inline

  Copyvar1 = 'hello' # rubocop:disable Naming/VariableNumber (here you can add a comment why)
  

  • multiline

  Copy# 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)

  CopyLayout/ArgumentAlignment:
    Enabled: false
  

• Excluding or including some directories in .rubocop.yml

  CopyLayout/ArgumentAlignment:
    Include:
      - 'spec/**/*'
    Exclude:
      - 'spec/bin/**/*'