Jekyll2026-08-06T22:56:03+00:00https://lovro-bikic.github.io/feed.xmlLovro BikićRuby StuffRuboCop Lazy Loads Cops Now2026-08-04T00:00:00+00:002026-08-04T00:00:00+00:00https://lovro-bikic.github.io/rubocop-lazy-loaded-copsA mildly exciting performance refactor has landed in RuboCop v1.89.0: lazy-loaded cops! In short:
RuboCop used to require all 600+ cops at startup,
it now autoloads cops instead of requiring them,
startup time has improved noticeably (10% up to 25%, depending on use case),
plugin maintainers should migrate to the new API for everyone to benefit.
The rest of the post is this summary expanded with details.
Requires Just Kept Growing
Some context first. Early versions of RuboCop didn’t have many cops. For example, v0.3.0 (released in 2013) had only 31; departments didn’t even exist as a concept. Back then, it was fine to require all cops in lib/rubocop.rb.
But RuboCop kept growing. By v1.0.0, the number of cops exceeded 400. They were still required the same way; as a result, lib/rubocop.rb was pretty long.
Today, there are more than 600 cops. And with plugins included (e.g. rubocop-rails, rubocop-rspec, rubocop-performance, etc.), that number is even higher.
Requiring so many cops wouldn’t be an issue were we to actually use them all in each RuboCop run. But we don’t:
you can run RuboCop with a single department (e.g. bundle exec rubocop -x runs only Layout cops),
or even a single cop (e.g. bundle exec rubocop --only Style/HashSlice).
Now a require in itself is not necessarily a slow operation, but hundreds of requires do add up:
This is a performance profile (created with Vernier) of a RuboCop run with a single cop on just one file. The many “icicles” in the red box are all the cops being required. Even if you can’t understand this chart very well, it’s quite obvious that the highlighted part sticks out.
So, at this scale, requiring all cops at startup is wasteful. To optimize execution times, a natural solution is to load a cop file only when the cop is going to be used, i.e. load it lazily.
Some Technical Details
Ruby already has an API to lazy load a class/module: Kernel#autoload.
You might think that to lazy load cops, you just have to replace require with autoload. If it were that easy, this would be the shortest section in the post.
Here’s the thing. All cops inherit from the RuboCop::Cop::Base class, which defines a class method inherited:
RuboCop::Cop::Registry is a class that saves references to cop classes. It’s used in various places in RuboCop, which I’ll get to in a bit. You create an instance of a registry and start adding cops to it (with #enlist).
Registry.global returns a global instance of the registry. You can, for example, call RuboCop::Cop::Registry.global.cops in the console to get a list of all cops.
So this callback adds a cop to the global registry whenever a cop class is created.
As was said, the registry is used in various places in RuboCop. Notably, Runner (which processes files for offenses) uses it to select cops to run based on .rubocop.yml and provided CLI options. If we don’t load cop classes, they won’t be added to the registry, and then Runner won’t work properly.
The lazy-loading initiative solved this problem in two steps:
A new method register_cop has been added to the API. It autoloads a cop class and adds the cop to the Registry as a stringified constant name.
Here’s an example:
# lib/rubocop/cop/lint.rbmoduleRuboCopmoduleCopmoduleLintextendLazyLoaderregister_cop:AmbiguousAssignment,"#{__dir__}/lint/ambiguous_assignment"# other cops...endendend
When lib/rubocop/cop/lint.rb is required, register_cop is called, which registers the cop Lint/AmbiguousAssignment under constant name "RuboCop::Cop::Lint::AmbiguousAssignment" in the global registry, and also autoloads the class (cop name and class name are the same).
Later, Runner accesses the cop from the registry, which calls Kernel.const_get to get the class, and autoload magic returns the AmbiguousAssignment class.
That is the gist of it. For in-depth details, please check out the PRs referenced in this issue.
Show Me the Numbers
Before the numbers, here’s the Vernier profile on lazy-loading RuboCop for the same scenario as above (single cop on just one file):
This is what we were aiming for, reducing the number of icicles.
Now for numbers. As was said above, speedup depends on the number of running cops. For simplicity, I’ve benchmarked all runs on a single Ruby file (multiple files naturally take longer) with caching disabled. All before and after runs have been repeated 30 times. Each run will display average execution time with standard deviation.
I’ll show you three RuboCop scenarios, in the order of most to fewest running cops:
After runs are on commit e9defb6 (when lazy-loading was added); before runs are on 8dc65e7 (the one before lazy-loading).
1. rubocop (Standard config)
For this setup, I configured RuboCop with Standard base config (353 enabled cops) and ran bundle exec rubocop --cache false.
Before: 1.650 ± 0.022 s
After: 1.473 ± 0.018 s
Execution time change: -10.73%
2. rubocop --only [department]
Similar setup to above (no Standard installed). I chose the Layout department. Around 100 cops ran.
Before: 1.578 ± 0.040 s
After: 1.280 ± 0.061 s
Execution time change: -18.88%
3. rubocop --only [cop]
Similar setup to above. I chose the Style/HashSlice cop.
Before: 1.554 ± 0.017 s
After: 1.138 ± 0.019 s
Execution time change: -26.77%
Interpretation
While the first before run is the slowest one, all before runs share similar execution times. This comes down to the fact that for a single file, most of the execution time is spent on startup rather than processing the file for offenses.
After runs have different times depending on the number of running cops. Fewer cops correlate with better times. The logical conclusion is that the best RuboCop times are achieved with all cops disabled.
Standard is a very popular config, so I would say that ~10% improvement in startup time is the realistic win of this initiative. But please note that for many processed files, the improvement won’t be as visible because the time spent processing files will overshadow startup times.
How To Migrate to the New API
Lazy-loading was only added to RuboCop itself, but plugins will still require cops unless they too migrate to the new API. RuboCop’s documentation has all the details on lazy-loading, so I’ll just briefly demonstrate how to migrate away from require.
Whereas before you’d have a file to require all cops:
That’s it, your plugin is now ready for lazy-loading.
Three things to note:
set minimum RuboCop version to 1.89.0 in the gemspec because of the new API
add extend LazyLoader to the module so you can use register_cop
provide an absolute path to the cop file in the second register_cop argument (hence the use of __dir__)
Depending on your plugin, there might be some other details to take into consideration. As a practical example, take a look at this PR that added lazy-loading to rubocop-rails.
I encourage plugin authors to use the new API so we can all reap the benefits of faster RuboCop.
Thanks Department
I got inspiration for this initiative when I saw this issue by Jean Boussier that included an idea to lazy load cops. While he started in the right direction, his proof of concept probably got stuck when it came to dealing with the cop registry and other bits. Nevertheless, it inspired me to give it a try. Thanks Jean!
After the first couple of PRs were merged, Koic took over and did gargantuan work to finish everything. I’m super happy this happened because it sped up the most tedious part of the initiative. Thanks Koic!
Last but not least, thanks to RuboCop creator Bozhidar Batsov for being on board with the whole thing — it means a lot!
That’s all, thanks for reading!
]]>rspec-mockbidden: Forbid Unwanted RSpec Mocks2026-04-19T00:00:00+00:002026-04-19T00:00:00+00:00https://lovro-bikic.github.io/rspec-mockbiddenProliferation of AI-generated code has caused a surge in mocks across test suites.
Some mocks I’ve seen have terrorized me:
let(:address){Hash.new}beforedoallow(address).toreceive(:fetch).with(:country).and_return('HR')allow(address).toreceive(:fetch).with(:province).and_return('Grad Zagreb')allow(address).toreceive(:fetch).with(:postal_code).and_return('10000')allow(address).toreceive(:fetch).with(:city).and_return('Zagreb')allow(address).toreceive(:fetch).with(:street).and_return('Trg Republike Hrvatske')allow(address).toreceive(:fetch).with(:house_number).and_return('15')end
When I get this kind of slop on a pull request, I don’t mind explaining there’s an easier way to construct a hash:
Now every time someone tries mocking a method on a Hash, their test fails with an error:
Hash is forbidden from mocking any instance method
AI, however, is not the reason I created this gem; it’s merely what pushed me to create it. The reason I created it is because, on codebases of a certain size, you need to communicate what is acceptable to mock and what should always execute.
For example, on the Rails codebase I’m working on, we use FactoryBot to set up test data with create and build methods. Code like this is not acceptable:
If we already have a database available in our test suite, we should use it (it will be used in production anyway, and that’s the reality we want to simulate in tests). If we don’t need database access in a test, build does the job.1
For fun, you can also forbid(anything).from receiving(anything), I won’t stop you (though it’s probably not realistic since mocks are sometimes valid).
I should note that when .and_call_original is used on a mock, an error won’t be raised. This, for example, is perfectly acceptable:
beforedoforbid(ApplicationRecord).fromreceiving(:first)endit'loads the first user only once'doallow(User).toreceive(:first).and_call_originalFirstUserService.callexpect(User).tohave_received(:first).onceend
forbid can be added anywhere in the test lifecycle:
it'forbids in the test'do# valid only for the duration of this testforbid(User).fromreceiving(:first)end# valid for any test where this hook is appliedbeforedoforbid(anything).fromreceiving(:call)end# mocking `ApplicationRecord#save` is forbidden for all tests in the suite# this is probably a good place for suite-wide rulesbefore(:suite)doforbid_any_instance_of(ApplicationRecord).fromreceiving(:save)end
The README has more implementation details and examples, including installation instructions.
The gem has been released today as v0.1.0. It has been tested on two production codebases, but it’s still an early version with a limited API. The API might be extended or changed, depending on real-world usage (e.g., forbidding multiple methods at once).
]]>300 Days of RuboCop2026-02-20T00:00:00+00:002026-02-20T00:00:00+00:00https://lovro-bikic.github.io/300-days-of-rubocop
It all moves along, however crowded, quite steadily at the rate of 25 miles per hour (Terran). Gethenians could make their vehicles go faster, but they do not. If asked why not, they answer “Why?” Like asking Terrans why all our vehicles must go so fast; we answer “Why not?” No disputing tastes.
— Ursula K. Le Guin, The Left Hand of Darkness
Hi, my name is Lovro and I spent 300 days adding a linter to a legacy codebase with one million lines of code.
What follows is an account of my initiative to add RuboCop to a Ruby on Rails codebase. I’ll talk about what set it off, my RuboCop proposal to management, why it got approved, my approach to enabling cops and fixing offenses, how I started contributing back to RuboCop, how others started contributing to the initiative, about fast and right solutions to problems, the opinions I gathered along the way, and, finally, when it was time to call it quits.
But I didn’t know any of that when I started.
I just knew there was a pull request, and my review had just been requested.
We’ve Been Here Before
I’m not shy when it comes to PR reviews. Incorrect code, performance optimizations, refactoring, simplification, stylistic nitpicks, poor grammar in documentation — all are equally deserving of a comment. When there’s an opportunity for educating the author (common for juniors’ PRs), I will jump on it. Sometimes, I also message the author with links to articles I think they could read.
One time, I left 230 comments on a PR. Nobody was happy about it, not me certainly, but I did tell the author many times before that big features need to be split into multiple PRs to make everyone’s life easier. Despite my pleas for best practices, still I was requested to review 7k lines of code at once. Well, I haven’t gotten a PR like that since.
Fast forward 5 years, I’m working on a different project in a big team. A massive legacy Rails codebase, code name Chaotic Beauty. Bugs cannot escape its gravitational field.
One day, a recently joined developer added a small-ish feature, and the PR link came my way. I opened it. I went through it once, scrolled to the top and started writing.
There were a number of issues with it. It was not unexpected; the dev was new to Ruby. I saw it as an educational opportunity for both parties. Out of the comments I left, I’ll highlight two pertinent ones.
The first one was for a unit test:
# spec/lib/tasks/users/employees_backfill_education_degree.rbRSpec.describeTasks::Users::SetEmployeeEducationLeveldo# tests go hereend
This test’s unit lives in lib/tasks/users/set_employee_education_level.rb. Notice how the test path doesn’t match the unit path. If I search for “set employee education level” in my editor, I’ll find the unit, but not the test. The path is not intuitive. When this anti-pattern scales to thousands of files, good luck navigating the codebase.
The second one was for a test variable, which initially looked like this:
let(:user){create(:user)}
I commented that create(:user) can be on the same line as let (3 lines are not needed for simple record setup):
let(:user){create(:user)}
He replied that the “syntax formatter is forcing this style”. That was true, but it was forcing it only because the dev put a whitespace between let and (:user), which is not preferred. It’s a method call, after all. Once the whitespace was removed, the suggested one-liner was allowed by the formatter.
There were other similar comments. We racked up 82 in total (“a few”, I think I said). I estimate my reviewing time was around an hour and a half. I guess it took the dev a bit more than that. And we both probably took a long coffee break afterwards.
In this estimation, I didn’t even account for that feeling of lost time that lingers even when the coffee break is over and you need to move on with your day. The situation got me thinking: should I propose RuboCop, again?
* * *
I had proposed RuboCop the first time about a year before. I suggested it to a staff engineer because we only had a syntax formatter at the time (and RuboCop is also a linter), but he was vehemently opposed to the idea. I can’t recall his arguments.
Weeks after the exchange, the same SE figured out we needed to replace the syntax formatter, which was Ruby plugin for Prettier. This time around, a colleague of mine mentioned RuboCop, but authority still wasn’t swayed. Something about how he (SE) didn’t have experience with it, and how he first wanted to turn on syntax formatting without linting (he wasn’t aware RuboCop supports that), and that too much time was spent already selecting the new tool.
First we switched to Rufo, then 3 weeks later we switched to SyntaxTree. The switch required a code freeze and a massive commit to restyle the codebase GitHub would prefer you wouldn’t open in the UI. It also caused collateral damage in the form of merge conflicts for the many open PRs, of which there were 150+ at the time (at any time, really).
Side note: you might like to know that Ruby plugin for Prettier is only a wrapper around SyntaxTree, meaning we ended up pretty much exactly where we began, with a little road bump in between. There is a guy pushing a rock up a hill who is very impressed by this.
I’m sure the ordeal didn’t imprint itself as a happy memory on anybody, and I wouldn’t have been thinking about switching formatters again were it not for the SE’s departure from the company, some time after the ordeal.
I saw the window of opportunity. Other ears would listen now, what could I possibly lose?
ROI, Nice To Meet You
I set up a channel (#rubocop-in-monolith), invited staff engineers and the engineering manager, then started writing. There was no plan, I let it structure itself naturally as I wrote. My first sentence was that I invited everyone because I wanted to open the discussion about enforcing RuboCop in the monolith.
The argument began by pointing out that we only have a syntax formatter, with which “you can still make tons of mistakes and all it will do is format them nicely”, as I wrote. As a matter of fact, it also adds trailing commas and forces single quotation marks for strings, but still, it’s not a linter.
I continued by claiming we hastily switched formatters (linking to relevant discussions), and that we keep switching them because they’re too simple and barely customizable (meaning, they have few rules, which can rarely be modified or disabled), something not acceptable for a monolith our size.
“As another point, and I’m sure you’re aware of this, there’s a fair amount of non-Ruby devs working on the monolith. Syntax formatting is not enough for them. It’s not enough even for me, and I’ve been writing Ruby almost exclusively for the past 5+ years.” I linked to the 82-comments PR, pointed out that only a minority of comments touched upon the business logic (yes, I’m partly to blame here), and also mentioned the amount of time it took to review it.
we can write custom cops to enforce rules specific to our domain,
it’s highly configurable (each cop can be disabled, and cops typically have configuration options),
it can be introduced gradually, cop-by-cop, with minimum friction (no code freezes and minimum merge conflicts),
it can co-exist with the current formatter until RuboCop is ready to take over.
I should have (but didn’t at the time) linked to specific cops like RSpec/SpecFilePathFormat and Lint/ParenthesesAsGroupedExpression that would have actually made my comments for unit test path and the test variable in that PR obsolete, thereby directly showing how RuboCop can save time.
I looked over what I wrote a couple of times, then clicked Send.
* * *
There is a presence in most stakeholder meetings. It takes many forms. Newcomers might be oblivious to it; others understand it instinctively. It manifests itself as employee productivity, time savings, customer retention, cost optimization… just to name a few. It is the life and death of technical initiatives. It is the invisible stakeholder with power of veto. It has a name too. We call it Return on Investment.
The technical crowd in the channel provided valid counterpoints for RuboCop. Its high configurability is a double edged sword because it can introduce bikeshedding, and requires strong ownership. False positives are not uncommon. It can pollute Git history (ignore revs file will help here). Some cop departments are more useful than others. We debated, more out of pure technical interest than anything else.
But out of everything I wrote, one point struck a major nerve: why are developers spending their time on things on PRs that can be resolved with tools, and not focusing on business logic? I was asked to estimate the effort of adding RuboCop.
The discussion continued for a while longer.
Stakeholders said they’ll get back with a decision. Two weeks later, it was approved. The scope was defined, I was designated the owner of the initiative, and work could begin. The feeling was a mixture of happy and anxious. I’m not shortsighted, this thing will obviously take a lot of effort. I have no idea what’s waiting for me.
Would I have succeeded had the staff engineer still been here? For one, it would have been rude to go behind his back and propose RuboCop a third time within a year, and this time to his leads. Alas. There’s a paraphrase of Max Planck that science progresses one funeral at a time; I guess a company’s unit of progress is a senior departure.1
This Mess We’re In
I added RuboCop and set up the CI workflow. The initial configuration looked like this:
The plan was to work on Lint department first, arguably the set of cops with the most useful rules. The claim will be substantiated shortly.
I opted to fix offenses not by auto-generating a .rubocop_todo.yml file, but by enabling or disabling one cop at a time from an empty config. There were no plans to mass fix multiple cops in huge PRs, even cops with safe autocorrect.
You can generate a report with the count of offenses per cop by running rubocop --format offenses (just make sure to comment out DisabledByDefault). The file is sorted by count, max offenses at the top. I worked from the bottom. Starting with cops that have only 1 or 2 offenses prevents one from being overwhelmed; that the first report had offenses for 450+ cops was overwhelming enough.
With the report in hand, I started fixing. Come with me on a road trip through my first PRs:
# offense for Lint/BinaryOperatorWithIdenticalOperandsifaddress.lng.nil?||address.lng.nil?...end# the author probably wanted to check if `address.lat` is nil too
# Lint/EmptyWhencasefoowhenBAR,do_this_pleaseend# the comma should not be there, `do_this_please` was intended to be executed when `foo` matched `BAR`
# Lint/DuplicateRescueExceptionbeginsomethingrescueStandardErrorhandle_errorrescueStandardErrorhandle_errorend# probably a result of a poorly handled merge conflict
# Lint/InterpolationCheckcontext'when state is #{state}'do...end# false positive if state really is '#{state}'
# Lint/RedundantSafeNavigationSomeModule&.foo?# why did someone think `SomeModule` could be nil?
# Lint/Voiddefitems[]ifDECLINED_STATUSES.include?(status)superend# the author intended the first line to be a guard clause, i.e. `return []`
# Lint/UnreachableCodedeffilter_discounts(discounts)returndiscountsdiscounts.select(&:applicable?)end# a quick business decision determined all discounts are applicable
# Lint/DuplicateMethodsclassFoodefbardoes_somethingend# ...200 lines later...defbardoes_something_elseendend# once again, probably a poorly handled merge conflict
# Lint/SafeNavigationChainuser&.address.country# if `user` is nil, `.country` will raise `NoMethodError`
# [insert offense for Lint/UselessAssignment]# so many variables assigned but never used... it took 9 PRs to remove them all
# Lint/ConstantDefinitionInBlockRSpec.describeFoodoMAX_RUNS=4end# while it might not look like it, `MAX_RUNS` is in fact a global constant
# Lint/ConstantReassignmentclassFooBAR=:bar# couple of lines laterBAR=:barend
# Lint/SuppressedExceptiondeffetch_first_key(hash,*keys)keys.eachdo|key|beginreturnhash.fetch(key)rescueKeyErrorendendend# exceptions used for control flow, a classic
Turns out, we needed a linter after all.
As I was fixing offenses, I also publicly documented PRs which fixed bugs. One has to feed ROI.
The work quickly turned into a routine. Turn a cop on, fix offenses, then pick another cop. Like an old man doing crosswords. And I would more than happily have continued emptying the report like this, had I not suddenly come to a halt.
The First Fork in the Road
One day, I enabled Lint/FloatComparison. It warns you when you use floats in (in)equality comparison because it’s unreliable (due to precision loss). But then it reported an offense for this line of code:
Float(latitude,exception: false)==nil
That didn’t seem right, it only checks if variable latitude is an invalid float string. I didn’t use Kernel#Float method before, but I ran it in the console and sure enough, given a string that cannot be parsed as a float, the left hand side of the expression returns nil. This code is correct.
Unknown to me at the time, this was a fork in the road.
The easy solution was this:
Float(latitude,exception: false).nil?
Refactor and move on. It’s even idiomatic Ruby. But that didn’t sit right with me.
It didn’t sit right with me because there might be more similar offenses in existing code (there were) or some dev might add similar code in the future and then be confused by the offense (wasting billed time, which does not appease ROI). But ROI aside, here’s the bigger picture: everyone who uses RuboCop will have devs likewise confused by the offense. Some might even think they’re doing something wrong.
I stared at the offense, and it stared back at me.
It was really hard not to look into the RuboCop source code — which I’ve never opened before — now being motivated by curiosity, economics, and a budding sense of accomplishment.
So I looked. I even said Hi! on my first PR, I think it’s good manners.
The first time is always the hardest. After searching GitHub issues and not finding mine, I forked the repo. RuboCop uses RSpec for its test suite, so that was familiar to me. I copied one of the existing tests for the cop and modified it to fit my scenario. It failed, as expected.
Then the hard part. Suffice it to say, after one too many breakpoints, I finally figured out the solution. Happy with it, I ran all checks and they passed. I don’t know why, but I was so nervous to open the PR that I re-read my patch at least ten times! Grammar, logic, formatting, PR checklist — I didn’t want to mess anything up. And it was only a few lines of code. When I finally realized I was being ridiculous, I clicked Open.
It was merged 65 minutes later. And I got a “Thank you!” What a dopamine hit. Followed by another, a few weeks later, when the PR was mentioned in v1.69.0 release notes.
After the first hit, I got interested. And with hundreds of cops still left to enable on a gargantuan project, it was the perfect environment to start an avalanche of contributions. But I will cover the lessons learned from the 70+ contributions that came from this and still keep coming in some other post. Back to the crossword. But first, a short break.
AI Pit Stop
I asked one of the popular LLMs about the offense, and it told me to use Float().nil? (easy solution) or to disable the cop (ignore-the-problem solution).
I continued prompting for different ideas — taking care to not be explicit as to the desired approach — but it kept proposing more code solutions, each more complex than the last (e.g., to save result of Float() in a variable, then check if it equals nil on a separate line, thereby avoiding the cop). Only when I pointed out that == nil is correct, it conceded the offense is a false positive and the best course of action is to report the issue. I guided it there.
But what if you let AI guide? If you didn’t know any better, you might have stopped at Float().nil?. AI tools certainly make that easy, when such solutions are only a keyboard shortcut away (and they come about even faster with agents). But amidst all that productivity, where did the time to stop and think go?
A fork in the road is a time to stop and think. Mine was a trivial one, yet it led me a long way. It could have just as easily led me nowhere. In fact, most forks do lead nowhere, but that just makes them more exciting when they don’t. But I never could have taken it had I not slowed down enough to see it, and not just be led the other way.
Applying the Boy Scout Rule
Ticking off cops from the report, I came upon Lint/UnusedMethodArgument. Here’s an illustrative offense:
The number of parameters is still the same, so existing method calls won’t break, and _user is clearly marked as unused. The solution is fast and correct. But is it the right one?
One of the goals of the initiative was to remove everything that’s redundant. Redundant code increases mental overhead. _user signals that we don’t have to pay attention to it, but it’s still there, and we have to provide it when calling the method. Plus, it got there because the method used to use the user argument, but then it was refactored to use only country. Meaning, this argument is a relic of the past. And past belongs in Git history.
So, I refactored all method callers to pass only country (and refactoring their callers as well if they didn’t need user anymore), then finally cleaned up the signature:
This might not sound supportive, but I don’t see the _user solution as adding much benefit to an already legacy codebase. If anything, it’s only a bit less noise. If you want to commit to your own RuboCop initiative, ask yourself whether you just want to get the job done or whether you want to leave the project in a better state than the one it’s currently in.
Moving Along Steadily
In Le Guin’s The Left Hand of Darkness, there is a chapter about the perilous journey Genly Ai (who is a human) takes over the Gobrin ice sheet over 80 days. Proportionally speaking, it is much much longer than the novel’s other chapters. It is a gruelling trip, but also an important one and rather beautiful. If it were shorter, you wouldn’t feel it.
Don’t worry, I’m not mentally preparing you for a long section. While it took 300 days2, the bulk of it was repetitive enough to not be novel material.
Part of the reason it took that long is because I didn’t spend my whole days on it. I wouldn’t do that even if I could; I’d go mad just working on linter offenses all day long. I squeezed this work in between regular work that brought money, which turned out to be anywhere between 0 and 3 hours a day. Plus, other free time was invested in RuboCop contributions.
The only rule of thumb I adhered to was that PRs needed to be small enough to be reviewable. Grouping multiple cops in a single PR was okay as long as there were one or two offenses per cop.
One thing I learned is how to say No to scope creep. Sometimes, when fixing a cop’s offenses, opportunities to refactor methods and classes presented themselves. They seemed to go naturally with the fixes. Despite their allure, it is imperative not to do those refactors in the same PRs, no matter how small they are. Justifying them with “Just this once, it’s a small change” is a mental trap. Make a note and fix them later.3 Otherwise, you’ll never get work done.
As a point of reference, I’ve enabled or fixed offenses for ~450 cops over the course of 360 PRs. If that sounds like a lot of work, that’s because it is, and not without reason.
Fans of De Morgan’s laws will notice something amiss. unless foo && bar is equivalent to if !(foo && bar) (or if !foo || !bar), not if !foo && !bar. But if you’re not careful enough, or trust the idea of safe autocorrection too much, this 3-year-old bug might evade you, even during a PR review.
RuboCop is a good tool, but it’s still made by humans. That’s why RuboCop’s changes should be treated just like anybody else’s. You would review a human’s changes, so you should review RuboCop’s too. Reviews usually aren’t effective when PRs are big. Hence, one small PR at a time. There are no shortcuts here.
Well, not without a cost anyway…
A Cowboy Takes the Shortcut
A test suite with high code coverage can help with some cops.
Style/MutableConstant is a terrific cop, but it comes with a caveat: when it freezes a constant, all code paths which try to mutate it will raise an error:
classShopDEFAULT_ITEMS=[:bicycle,:camera].freezedefself.sellable_items(user)items=DEFAULT_ITEMS# raises `FrozenError` because `<<` mutates arraysitems<<:fridgeifuser.fridge_supported?itemsendend
When .freeze is added to DEFAULT_ITEMS array, the only way you can be sure this code will still work is if Shop#sellable_items has sufficient code coverage.
The situation I found myself in when I wanted to enable the cop was this: code coverage was low (< 20%), and there were more than 5200 constants that needed freezing. It’s not an ideal situation.
When I saw the offense report, I couldn’t help but be overwhelmed. Unlike other cops with many offenses (even cops without autocorrection support), the “right” way to fix offenses was tedious: go constant-by-constant and check each reference to see if it’s mutated at some point (which requires reading all relevant code and knowing which APIs have side effects).
Assuming a constant is referenced an average of 2 times (most constants are referenced only once, but some are referenced 100+ times), and that each reference takes 10 seconds to read through (optimistic, yes), 10400 references would take at least ~29 hours to check. Even my tenacity has its limits.
I debated with myself how to resolve the challenge, but didn’t have a good solution in mind. When I tried freezing all constants in a dry-run PR, the CI failed with errors for the code that was covered by tests, but I assumed that was just the tip of the iceberg. And because of our staging environment setup, deploying the dry-run PR for QA testing would be feasible only for critical flows, which were already covered by unit tests.
Out of ideas, I decided to autocorrect the offenses and deploy to production, accepting the possibility of errors. I told myself that code which mutates constants is buggy anyway, so temporary errors aren’t really that much worse than “working” bugs. I announced in the initiative channel what I was about to do and what it entailed, and also that the work will be spread over a couple of days to soften the blow. We also have application monitoring, I could keep my eyes peeled for FrozenError.
I merged one PR a day over the course of a week. As expected, there were errors. Three, to be exact, or 0.06% of all frozen constants. And fortunately all of them in non-critical code paths. That’s the thing about icebergs, you never know how deep they run.
This was the only cop in the initiative I handled the cowboy way. I didn’t know any better then. I don’t recommend the approach because it’s not professional, but sometimes it’s a cost-effective solution. If you’ll take that approach, the least you can do is be upfront about it and to spread the impact.
AI Pit Stop 2
As I was finishing up this section of the post, it occurred to me that I could have asked AI to give me ideas for the problem. This might sound inconsistent with my opinion on AI in the first pit stop, but it’s actually not.
I’m not dismissive of AI; it’s just a tool. A tool has its uses. Each use has its advantages and disadvantages. It takes time to be aware of them. Taking time is not being dismissive, but it might certainly look like it in this ever accelerating world.
Anyway, I wondered whether I could track constant mutations somehow, so I asked one of the reasoning models to give me a couple of ideas. The options it provided gave me an idea to use Module#const_added and a custom Rack middleware to figure out which constants are mutated in a request by comparing the state before and after, which would be enough information for me to then track down the mutation in code. In the end I had a working solution which I could use in production. It comes with some performance and memory overhead, but for temporary instrumentation I think that’s acceptable.
Looking back, I wish I had spent a bit more time thinking before freezing all constants. I looked into official documentation, Stack Overflow questions, various forums and read through Ruby issue tracker, but still, I didn’t connect the dots. In such cases, I don’t think using AI is a bad idea to explore options one might have missed or hasn’t thought of.
Sharing the Sheriff Badge
One of the advantages of RuboCop I highlighted is the ability to write custom cops. This would allow us to enforce rules specific to our codebase, for many people who come and go on the project. I knew that some big players utilize this feature well (GitLab, for example, has over 200 custom cops at the moment), but I didn’t have any ideas in mind for our monolith, even when I was already a couple of months into the initiative.
Turns out, other people would come up with ideas for cops themselves.
We use the Typhoeus gem for HTTP requests to different external services. By default, the gem doesn’t enforce a timeout for the total request duration. You could set a global timeout as a fallback, but that won’t cut it when some services should allow max 5 seconds, and others even up to 1 minute. The problem we had was that many places in our codebase didn’t use a timeout, which was a big issue for app reliability.
So, one dev came up with a cop to scan usages of Typhoeus API and enforce setting a timeout. With it, we identified all places where timeouts were missing, fixed them, and also made sure all future devs will be made aware you don’t want to run HTTP requests forever.
A month later, a cop for DB migrations appeared. Then, one for freezing YAML objects on load, another for not setting an explicit autoincrement column in factories, and so on. As patterns and anti-patterns emerge on the project, I’m sure even more cops will be created in the future. And if they’re generic enough, we can even try upstreaming them to RuboCop.
Of course, not every pattern should be a cop. Custom cops make sense when you can reliably implement them (with little probability of false positives) and when they would catch offenses often enough (spending 3 hours writing a cop to catch 2 nitpick offenses in a year is probably best left to manual review). A cop is something you have to write, test, document and maintain, so the cost must be justified.
And when cost is involved, there’s one cardinal mistake you don’t want to make.
Staying on ROI’s Good Side
The days were going by. Cop after cop, department after department, the report was getting shorter and shorter. After Lint, I turned to FactoryBot, RSpec, Security, Naming, Rails, Performance, Style and Layout departments. I worked sometimes by department and sometimes by the number of offenses.
FactoryBot, I enabled almost all cops. RSpec, Security and Naming too. We needed about a half of Rails cops. A third of Performance cops, the ones which didn’t impact readability that much. A little more than a half of Style cops. The whole Layout department (with some customizations).
I disabled the Metrics department altogether. Existing classes and methods were long and complex, and refactoring all that code was not in the initiative’s scope. But even if this were a new project, my experience with this department is that the rules are just too context-dependent to be generally useful.
To find out how others feel about Metrics, I did a little analysis of real-world-rails for rubocop:disable directives. Here are statistics for disabled RuboCop-only cops grouped by department, at the time of writing:4
I don’t think Metrics cops are without merit (sometimes an offense will prompt me to refactor a method and I’ll end up with something cleaner), but the noise of directive comments is also something to consider. Plus, with rampant use of AI, the models tend to bend code over backwards to comply with the cops. Food for thought.
When there were around 50 cops left in the report, I started feeling saturated. It wasn’t that I got bored of the initiative, it was more that the remaining cops seemed to become less and less useful.
It began with a cop like Style/DoubleNegation. Like yes, I could change !!something into !something.nil?, sure. Or I could break up couple of chained multiline blocks to tick off Style/MultilineBlockChain from the report, but why? Like Metrics, I don’t think these cops are without merit, but after I’ve fixed bugs, removed redundant code, simplified things, improved consistency, performance and syntax formatting, these remaining cops felt like playing with variations of the same code, one not that much better than the other.
So when I looked at the report and saw only such cops, I knew my job was done.
That is, from the technical side at least.
Don’t Forget About Others
Being intimate with RuboCop, it’s easy for me to overestimate how much the average developer is at ease with it, and easy to forget I’m not the only one using it. Sigh. The fun part is over, documentation drudgery begins.
I opted to write docs in the repository README. They explain:
what is RuboCop and what we are using it for (linting and syntax formatting),
how to autocorrect only layout offenses (-x flag),
the difference between safe and unsafe autocorrection,
our policy for disabling cops (which is: prefer not to, but if you must, explain the decision in the cop disable comment),
editor integrations (e.g. Ruby LSP, Solargraph), and
how to deal with CI failures.
If you’re using RuboCop daily, these items might seem obvious and not worth documenting. Just remember that there was a point in time when you didn’t find them obvious either.
GitLab is also a good example in this regard. But whatever you choose to write, just make sure to adjust the language to the skill level of your team.
Burning issues are also a part of the initiative. Sometimes, CI would fail for random reasons. Other times, new code with offenses would be merged to master minutes after I enabled a cop. Less burning, but sometimes people would ask how to fix offenses for some cops and we’d discuss it. And then there was scheduled work, like periodically updating RuboCop and fixing new offenses.
On the topic of failing CI, I think it’s a good idea to check other people’s failing runs to see how adoption is progressing, and if there are areas for improvement. I typically spot check the runs from time to time. Also, since our CI has an API for fetching workflow logs, I wrote a script to extract some offense statistics.
Here are, for example, the top 20 failing cops for the past ~3k workflow runs:
There were 3432 offenses in total for 151 cops, meaning the top 7 cops (~5%) account for ~62% of offenses. Notice how the top 7 cops are autocorrectable (one exception being Layout/LineLength, but only sometimes).
This suggests I could raise tooling awareness in the team. For example, I could tell people that some editors support trimming trailing whitespace on save (thereby avoiding Layout/TrailingWhitespace offenses). Or, I could come up with a solution to autocorrect some of these cops on file save, which people could then integrate with their editors (these cops’ safe autocorrect can generally be trusted).
One more use of this data is to check how many would-be issues and bugs have been prevented without PR reviews. While not shown in the top 20, RuboCop also caught Lint offenses similar to those when I just started the initiative. And while I’m sure most would be caught during a PR review, this is still saved time for everybody.
Speaking of time. I believe I’ve shared every relevant fact and figure, and probably one too many opinion. But now, almost 6 months after the final PR, I don’t think much about any of that. What I do think about, though, is one question:
Twenty Seven Thousand Green Dots
Given the opportunity, would I do it all again? That is, if I were to work on another huge legacy codebase, would I go through the same trouble of convincing management we need a linter and setting off months of menial work?
Yes, with a caveat.
When I began, I didn’t know that much. I didn’t know that what makes management accept an initiative is not a well-reasoned essay, but usually some guy called ROI who doesn’t care whether you like him or not. And I didn’t know how to start working, except by fixing one offense, and then another. I also didn’t know how to contribute to one of the most popular Ruby libraries out there, which, I previously assumed, was a done project that would have little use of me. And I for sure didn’t know how much time it would all take, though I did give an estimate (for some reason, I always have to).
But what I truly didn’t know is where that time would take me, and what I now know is where it could take somebody else.
My 300 days taught me many things. Another 300 would probably teach me a bit more (though honestly, I’d be on the lookout for RuboCop contributions the most), but I also know that diminishing returns are a thing, and that, even if they weren’t, interests change. Mine certainly have.
Therefore, my caveat is that I’d only do the whole thing again, but as a mentor.
There is, in fact, a sea of opportunity in menial, repetitive work; we just don’t tend to see it. The reason is simple.
We underestimate such work from the very start by assuming there’s nothing to learn from it. Because of that assumption, we don’t focus on the work fully. By not focusing fully, we miss the hidden opportunities. By missing the hidden opportunities, we end up exactly where we assumed we would.
* * *
I’ve given glimpses into the monolith with figures and examples. One figure I didn’t give is that the 1+ million lines of code are split between 27 thousand files. There’s a quote attributed to Bertrand Russell that “The mark of a civilized man is the capacity to read a column of numbers and weep.” I’m not sure he had monoliths in mind.
As much as I’d like to, I can’t weep over a million lines of code. It’s a number that sounds great, but my senses just don’t react to it. A couple thousand, on the other hand, is a magnitude much familiar to my senses. After all, I’ve been looking at it for 300 days.
The chaos that magnitude brings is out of control of any living being. Good engineering can create lasting architecture, optimize API endpoints, reduce infrastructure costs, succinctly and transparently document decisions, write code that can change almost as fast as business decisions, but it can’t keep track of all lines of code forever. Tools can.
* * *
When you run RuboCop, by default it will print a character per checked file to terminal output. An offense might result in a red E (error) or a magenta W (warning). For no offenses, you get a green dot.
I must have run RuboCop hundreds of times during the initiative. The slowness on a huge codebase bothered me enough to optimize it for CI, which I then upstreamed to Rails. Each run would first pause for a couple of seconds as RuboCop was warming up, then dutifully print out 27 thousand characters to inform me of the verdict. It was so annoying to see one E in what was otherwise a sea of green dots.
But overall, it was good work and I liked it. I like what it brought, and that I didn’t know what that would be.
……………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………………… Chop wood, carry water, fix offense
Footnotes
If you find the statement cold, just know I’m a senior too. ↩
301 days to be precise, but developers are permitted off-by-one errors for marketing purposes. The first PR was on Oct 30, 2024, the last one on Aug 26, 2025. There were some PRs after that, but they were for periodic RuboCop updates as part of post-initiative support. ↩
Lint/UnusedMethodArgument is an exception since the autocorrect would produce unfavorable code. ↩
This is the command I ran in the terminal on the real-world-rails repo to get the disable directive statistics: grep -ohrE "# rubocop:disable .+" real-world-rails/apps | grep -oE "(Bundler|Gemspec|Layout|Lint|Metrics|Naming|Security|Style)/" | sort | uniq -c | sort -nr↩
The command is very similar to above command, and is left as an exercise for the reader. ↩
]]>Real-World Data RuboCop Offense Reports2025-08-30T00:00:00+00:002025-08-30T00:00:00+00:00https://lovro-bikic.github.io/real-world-data-rubocop-offense-reportsWhen contributing to RuboCop, I oftenincludereal-worldoffense reports in pull request descriptions to show that cops I want to add or changes I plan to make will have a sizeable impact. I also do this because running anything on real-world data can surface potential implementation bugs.
In this post, I’ll show where I gather real-world data from and how I generate reports that can be shared with others. The reports include GitHub/GitLab links to specific lines of code, and they look like this:
# https://github.com/gitlabhq/gitlabhq/blob/ba8e6fd9f408a6a6e0d20a5fe0d378aa63247065/app/models/concerns/mentionable.rb#L200source.select{|key,val|mentionable.include?(key)}# https://github.com/gitlabhq/gitlabhq/blob/ba8e6fd9f408a6a6e0d20a5fe0d378aa63247065/config/initializers/fog_google_list_objects_match_glob_support.rb#L34**options.select{|k,_|allowed_opts.include?k}# https://github.com/gitlabhq/gitlabhq/blob/ba8e6fd9f408a6a6e0d20a5fe0d378aa63247065/lib/gitlab/ci/reports/test_suite_comparer.rb#L31-L33head_suite.failed.selectdo|key,_|base_suite.failed.include?(key)end.values# etc.
This is neat because you can see where the offenses have been caught (which, among other things, allows you to find false positives), they’re syntax-highlighted, and anybody can open the link to view the offense in context. The offense message is not displayed because in such reports it is less important; the code matters more.
First, I’ll talk about fetching real-world repositories on which to run RuboCop. Then, I’ll explain how to generate the reports with a custom RuboCop formatter.
Real-world repositories
When we talk about real-world Ruby data, it’s important to distinguish the type of data we need. For contributions to rubocop-rails, we’d like to have Rails repositories; likewise for rubocop-rspec, rubocop itself, and other similar gems.
I most commonly contribute to those three gems, so having relevant repos comes in handy. Fortunately, kind folks have compiled repos with real-world applications that can be quickly cloned.
These repos use submodules to fetch other public repos. After following the installation steps from one of these repos’ READMEs, you’ll have lots of Ruby code checked out locally. This is the code on which we’ll run RuboCop.
The apps in these repos have their own .rubocop.yml files. While needed in the context of the project, we don’t want project-specific configuration to affect our RuboCop runs, so we’ll delete them:
# cd to the real-world folder, then:
find .-iname'.rubocop.yml'\(-type l -o-type f \)-delete
This will delete both files and symlinks named .rubocop.yml recursively.
Now we have the code ready locally. Next step is to create the RuboCop formatter.
Custom formatter
To print the offenses with links, I wrote a custom RuboCop formatter which you can find in this GitHub gist. It’s based on the Clang formatter, and it should replace the clang file in your local clone of RuboCop (you can also replace any other formatter if you prefer that).
The formatter uses Git to get the current revision of the file and the remote where it’s hosted, then constructs a URL from the rev and the line number, giving you a permalink. Also, unlike other formatters, if an offense spans multiple lines, it prints all lines instead of only the first one.
I keep the patch with the custom formatter stashed locally, and whenever I need it, I just apply the patch.
Running RuboCop
When I run RuboCop on real-world data, I typically run it with one cop I’m adding or modifying.
Assuming the real-world repo is cloned in the same parent folder as rubocop, you can generate the report by running RuboCop from the rubocop folder, for example:
If all went well, report.rb should contain offenses for the cop (in this case, Style/HashSlice) for all applications from real-world-ruby-apps, formatted with public references. I save the report in a .rb file to get syntax highlighting in the IDE, which usually works, though highlighting may break depending on the offense code.
That’s it. I wish you good fortune in the contributions to come.
]]>Consistent MySQL structure.sql Diffs for Rails2025-07-29T00:00:00+00:002025-07-29T00:00:00+00:00https://lovro-bikic.github.io/consistent-mysql-structure-sql-diffs-railsJump to recipe ↓
Having worked most of my Rails career with PostgreSQL and schema.rb files, when I had to switch to MySQL and structure.sql for a new project, the proverb “We don’t appreciate what we have until it’s gone” grinned at me again.
It grinned because I hadn’t appreciated that, when running a migration, only the relevant part of the structure dump would change. Nor had I appreciated the db:schema:dump Rake task (and the now obsolete db:structure:dump) which would yield consistent results, unaffected by local data.
With MySQL, the story is different. For one, the structure dump contains the pesky AUTO_INCREMENT option for each table. The value of this option depends on the data at the time of the dump, and there’s no flag to exclude it from the output. If multiple people work on the same codebase, they can get different dumps, despite running the same migrations. This bug has been open since June 2006, way back when I had just finished first grade (times which I now appreciate).1
Then, not everybody uses the same MySQL client. For example, I prefer local development and use MySQL installed via Homebrew, which ships with mysqldump. Some colleagues work in containerized environments that come with MariaDB and, by extension, mariadb-dump. The output of mysqldump and mariadb-dump is similar, but not identical.
On the new project, the way to commit structure.sql was to fish out your schema changes from the diff soup, which looked a bit like this:
These diffs would repeat for all tables. More than once, they have caused accidentally committed lines and bad merge conflict resolutions. We kind of accepted the fact that db/structure.sql was to be found in unstaged changes at all times, even if your work didn’t touch the schema.
I don’t remember exactly which straw broke this camel’s back, but at some point I became determined to:
resolve all differences between mysqldump’s and mariadb-dump’s outputs, and
make structure dumps idempotent (i.e., dump the same schema twice, get the same output),
so that migrations update only the parts of the structure dump you intend to change and nothing else. The solution turned out to be normalizing the structure dump with some regexes. It’s a simple recipe, but it goes a long way.
Recipe
# lib/tasks/db/schema/dump.rakeRake::Task['db:schema:dump'].enhancedostructure_sql_path=Rails.root.join('db/structure.sql')ifFile.exist?(structure_sql_path)sql=File.read(structure_sql_path)# see https://dev.mysql.com/doc/refman/8.4/en/example-auto-increment.htmlsql.gsub!(/ AUTO_INCREMENT=[0-9]+/,'')# see https://mariadb.org/mariadb-dump-file-compatibility-change/sql.gsub!(/^.+enable the sandbox mode.+$\R/,'')# mariadb-dump prints the former, mysqldump prints the lattersql.gsub!('/*!40101 SET NAMES utf8mb4 */;','/*!50503 SET NAMES utf8mb4 */;')sql.gsub!('/*!40101 SET character_set_client = utf8mb4 */;','/*!50503 SET character_set_client = utf8mb4 */;')File.write(structure_sql_path,sql)endend
With this script, when you invoke bundle exec rails db:schema:dump, Rails will first create a new structure.sql file, and then it will run the block.
The logic first checks if db/structure.sql exists. This is a precaution in case the dump fails for whatever reason, so that we don’t try to operate on a nonexistent file. If it does exist, we normalize it:
Removing AUTO_INCREMENT
The first step is to remove all traces of the AUTO_INCREMENT option:
sql.gsub!(/ AUTO_INCREMENT=[0-9]+/,'')
which will in practice adjust all CREATE TABLE statements like so:
AUTO_INCREMENT=value tells the DB the next value for the AUTO_INCREMENT column. In the above example, id is that column, and the current value is 123. When we insert a new row in table foo (and don’t set the id explicitly), its id will be 123. After insertion, the AUTO_INCREMENT value will increment by one, becoming AUTO_INCREMENT=124.
As you can see, this is a data-dependent option, so it’s not that useful in our schema. Removing it will implicitly set the value to 1 when you load the schema (e.g., in your test environment), which is great.
Removing MariaDB’s sandbox mode comment
If you’ve worked with MariaDB before, you may have noticed this line at the top of your structure.sql:
/*!999999\- enable the sandbox mode */
You won’t find this with MySQL. To resolve the difference, the script removes the line:
The last step is to normalize executable comments:
sql.gsub!('/*!40101 SET NAMES utf8mb4 */;','/*!50503 SET NAMES utf8mb4 */;')sql.gsub!('/*!40101 SET character_set_client = utf8mb4 */;','/*!50503 SET character_set_client = utf8mb4 */;')
The exact replacements depend on your MySQL and MariaDB versions, but let me first briefly explain how these comments work.
For example, this comment:
/*!40101 SET NAMES utf8mb4 */;
will execute the statement SET NAMES utf8mb4 only if your MySQL/MariaDB server version is greater than or equal to 4.1.1 (version format after ! is Mmmrr, which stands for Major version, minor version, and release number). More on this here.
Structure dumps include a bunch of these comments, but the problem is that MariaDB and MySQL differ in the version specified in the comment, and sometimes even in the statement that’s executed.
On my project, MySQL will print out /*!50503 SET NAMES utf8mb4 */;, while MariaDB prints out /*!40101 SET NAMES utf8mb4 */;. To resolve the difference, I’ve opted to adjust MariaDB’s comment so it matches the MySQL one. Instead of executing on version 4.1.1 and above, the statement will now execute on v5.5.3 and above.
This is acceptable for us because our versions of MySQL and MariaDB are both greater than 5.5.3. If you’re not sure which server version you’re running, you can check this through the Rails console:
The SET character_set_client = utf8mb4 statement is treated in a similar manner. Unfortunately, I can’t guarantee that the examples I’ve shown here will apply to your use case (since these comments change with MySQL/MariaDB versions), but what I’ve hopefully shown is how you can resolve the differences on your own.
Outro
With the script in place, run db:schema:dump and commit the normalized structure dump. The next time a migration runs, structure.sql diff should include only the changes that actually need to be committed.
Make sure to also run db:schema:dump when you update MySQL or MariaDB to a newer version, to verify the script still works. If there’s an unwanted diff (most likely due to new conditional comments), a small adjustment to the script should hopefully remove it.
As for my project, I can’t even imagine going back to the old way of dealing with persistent diff noise. In this case at least, I appreciate the present more.
]]>Making Sure FactoryBot Builds Without Creating2025-07-04T00:00:00+00:002025-07-04T00:00:00+00:00https://lovro-bikic.github.io/factory-bot-build-without-creatingJump to recipe ↓
factory_bot is a great gem for writing factories in Ruby tests. It supports multiple strategies to instantiate records, the most familiar of which are create and build.
build simply returns an unpersisted record with set attributes and associations (also unpersisted, if configured properly), while create additionally saves it in the database.
Which strategy we use in which test depends on what the code does; if the code we’re testing interacts with the DB, we probably want to create records. But if we’re testing something DB-independent, like a model method that only uses attributes, then building is enough, and also preferable since it’s much faster than creating.
Unfortunately, on most projects I’ve worked on, I’ve encountered (and, admittedly, sometimes written) factories that would execute SQL queries even when you’d build them, which leaves the test suite in an unoptimized state.
It would happen for various reasons, e.g. an association defined using create:
FactoryBot.definedofactory:petdoveterinarian{create(:person)}# FactoryBot.build(:pet) still INSERTs a person in DBendend
or a build callback that does something in the DB:
FactoryBot.definedofactory:petdoafter(:build)do|pet|pet.bite_the_vet!# presumably, updates last_bitten_at column on the poor vetendendend
I recently spent some time optimizing the test suite on a project with more than 250 factories and plenty of traits. However, checking each factory’s build behavior individually was tedious. To help myself find non-buildable offenders — and prevent them from being introduced in the future — I wrote a spec that uses the handy rspec-sqlimit gem to check that for me:
If any built factory executes an SQL query, the test will fail, and the output from rspec-sqlimit will show you which queries ran, helping you pinpoint the cause.
Of course, if some queries are unavoidable even when building (maybe some SELECTs), then you can pass additional options to the exceed_query_limit matcher to exclude them.
That’s all, thanks for reading!
]]>Running RuboCop on GitHub Actions With Cache2025-03-13T00:00:00+00:002025-03-13T00:00:00+00:00https://lovro-bikic.github.io/github-actions-rubocop-workflowHere’s how to set up a RuboCop workflow on GitHub Actions with caching for faster workflow runs.
This workflow has been battle-tested on a rather active Rails monolith where running RuboCop would take 8 minutes without cache. Fortunately, caching drops that time to ~40 seconds.
The workflow assumes you have a Gemfile that includes the rubocop gem.
Finished product first, followed by a detailed breakdown. This can be copy-pasted, but you might need to adjust it to fit your own needs.
Mechanism to limit in-progress workflow runs to one per branch. In practice, if you push a commit to a branch while a workflow is already running for a previous commit, that run will be cancelled.
Workflow triggers
on:pull_request:push:branches:-master-main
Defines events that trigger the workflow.
pull_request will run RuboCop when a PR is opened or updated, for example.
push will run RuboCop on pushes to the default branch (master/main). This is used to both verify the latest commit passes RuboCop and to update the cache (more on that below).
Defines the job and its runner and timeout. Adjust the timeout if necessary, but keep it as low as possible in case a workflow run gets stuck so you don’t get billed for wasted minutes (default timeout is 6 hours, which could cost you a couple $$ if something goes awry and you don’t notice it (speaking from experience)).
This part of the workflow also sets up the RUBOCOP_CACHE_ROOT environment variable to save RuboCop cache in the tmp/rubocop folder. This is the folder we’ll be saving in GitHub Actions cache later on.
Repo setup
steps:-name:Git checkoutuses:actions/checkout@v4-name:Set up Rubyuses:ruby/setup-ruby@v1with:bundler-cache:true
The path we’re caching is defined in the environment variable RUBOCOP_CACHE_ROOT that was set on job-level. Setting this folder explicitly ensures RuboCop cache is located in the same folder that GH Actions caches.
hashFiles returns a hash of a given set of files and this particular set aims to follow RuboCop’s cache validity rules. An existing cache won’t be used in a later run if:
Ruby version changes (assuming there's a .ruby-version file), or
RuboCop version changes (technically, cache will be invalidated any time Gemfile.lock changes, but this is a pragmatic choice to not overcomplicate the setup).
Finally, ${{ github.ref_name == github.event.repository.default_branch && github.run_id || 'default' } is added to ensure the default branch has up-to-date cache (its cache key ends with workflow run ID, which changes for each commit). Other branches have a single cache (their cache key ends with default).
When restoring cache, if there’s no exact key match, we try to restore the most recent cache that matches the prefix rubocop-cache-${{ runner.os }}-${{ env.DEPENDENCIES_HASH }}-
How does this setup function in practice?
On all branches, if dependencies (runner OS or DEPENDENCIES_HASH) change in a new commit, cache is not restored and RuboCop has to scan the entire codebase from scratch. Consequently, these runs are the slowest ones. When they finish, their RuboCop cache is saved for later use.
On the default branch, each commit creates a new cache entry as means of “updating” the cache. Cache from a previous workflow run is restored if dependencies match, but it will always be saved under a new key. This is necessary because GHA cache is immutable so when there’s a cache hit you won’t be able to update its contents. If we don’t “update” the cache, it will become less and less useful over time as source files change (RuboCop invalidates a file’s cache if its contents change).
On branches other than the default, first workflow run will try to restore the most recent cache from base/default branch. The cache will be saved under a key ending in default when the workflow finishes. If dependencies don’t change in a later commit, this will be the single cache entry for that branch.
A branch’s default cache might not be so useful in a later commit if you change a bunch of files, but this setup works okay for most workflows (for example: first commit changes the most files, and later commits update only some files after a PR review, so most of the cache is still utilized).
GitHub Actions formatter will add nice annotations in the UI if there are any offenses. Clang formatter is useful if you want to inspect workflow logs.
Enjoy!
PS: A note for large codebases
At the time of writing, RuboCop by default saves max 20k files in cache. If your codebase is larger than that, you’ll want to update your configuration so it caches everything in the codebase to ensure optimal workflow times.
Here’s how to quickly check the number of files RuboCop will scan:
$ bundle exec rubocop --list-target-files | wc -l
Then, update MaxFilesInCache in your .rubocop.yml to a value greater than that.
