Gradually Introducing Rubocop
Rubocop is a great tool for ensuring a consistent coding style in any Ruby (and/or Rails) project.
It’s incredibly configurable - it needs to be (Rails developers are nothing if not opinionated).
Adding Rubocop to your CI/CD pipelines can be a great step towards making sure that all the code within a project sticks to an agreed set of standards for style.
But if you’ve got a large project that’s been around for a while and you’re considering adding Rubocop late in the game, you may feel daunted by the sheer number of ‘violations’ that Rubocop will find.
If your project is scanned by Rubocop and is reported to have ten thousand violations, what are you supposed to do with that information?
You’re not really in a better position than you were - fixing those violations could take weeks or months, and having a failing pipeline is no use to anybody.
It turns out Rubocop has a really nice built-in way to help you with this.
When I was first exploring Rubocop for big old ugly projects of my own, this was not immediately obvious. They should definitely lead with this on the Rubocop documentation homepage.
Enter rubocop --auto-gen-config
All you need is the rather blandly named option:
rubocop --auto-gen-config
This does exactly what we need - in an ideal world the command would look more like…
rubocop --temporarily-pardon-all-existing-violations-for-me-to-address-later
…but I guess they thought that was a bit of a mouthful.
After you’ve run rubocop with the --auto-gen-config option, you’ll find two important new files
in your project directory:
.rubocop_todo.yml
.rubocop.yml
The .rubocop_todo.yml file contains configuration entries that disable cops for any existing offences that were found in your codebase when the command was run.
Essentially, this file tells Rubocop, “Yes, we know these violations exist, but please ignore them for now.”
Hang on…What’s the point of silencing violations?
Silencing existing offences might seem counter-intuitive at first - why run Rubocop if we’re going to ignore what it has to say?
The idea is, we ‘fess up to all the current offences and then get Rubocop running as a gatekeeper to make sure no new offences slip in.
And meanwhile, the development team can gradually address all those ten thousand violations that were found when we first added Rubocop.
Gradually re-enabling cops
Because .rubocop_todo.yml is just YAML, you can start re-enabling cops one by one as you clean up violations. A typical workflow might look like this:
-
Open up
.rubocop_todo.yml, and pick one of the cops - maybe one with just a couple of violations, or maybe one that’s been annoying you for a while and crying out to be fixed. -
Fix the offences manually or use
rubocop -Ato attempt auto-correction. -
Delete that cop’s entry from
.rubocop_todo.yml. -
Commit and push. Now that cop is active in your project and enforced going forward.
Over time, the .rubocop_todo.yml shrinks, and your code quality improves.
Seeing .rubocop_todo.yml shrinking over time is surprisingly satisfying.
Conclusion
Introducing Rubocop into a legacy Rails project doesn’t have to be painful or overwhelming. With --auto-gen-config, you can defer existing issues, enforce standards on new code, and clean up old violations at your own pace. It’s the best of both worlds: modern code standards without stopping the world to refactor everything.
So go ahead — run the command. Silence the noise. Then, start chipping away. Future you (and your teammates) will thank you.
This page was handcrafted in Brighton by Codeface