The upgrade has been on the someday list long enough, and now someone wants it on the roadmap with a number next to it. The honest answer is a range that sounds useless at first: anywhere from an afternoon to several months. But the spread has structure. Duration is the number of version hops between where you are and where you’re headed, multiplied by how long each hop takes, and a handful of measurable factors set that per-hop time. You can score those factors against your own app in about an hour, and this page walks through how.

For a single major hop on an app that has been kept current, expect days to a couple of weeks of engineering effort. Our published guidance, from our Rails 6 to 7 guide, is to budget roughly a week per major hop for a mid-sized app with decent tests. At the easy end, an app already on Rails 7.2 with a green suite can land the 8.0 version bump in an afternoon; our Rails 7 to 8 guide walks that hop end to end. At the hard end, an app several majors behind with a Webpacker-era front end is looking at months, because the preparation is the real project and the framework bump is the small piece at the end.

One distinction before any of those numbers can mean much: engineering effort and calendar time aren’t the same thing. An upgrade can consume two weeks of effort spread across a quarter of calendar, because the safe way to ship it includes deliberate waiting between deploys. Most published numbers blur the two, so we’ll keep them separate below.

The official Rails upgrade process moves one minor version at a time: get onto the latest patch release of the version you’re on, fix every deprecation warning, hop to the next minor, and repeat. The Rails upgrade guide is explicit about this, and it means version distance is the first multiplier in any estimate. An app on 5.2 heading for 8.0 has six or more hops in front of it, and each hop is its own small project with its own deploy.

The release calendar tells you how fast hops accumulate. Rails aims to ship a feature release roughly every six months, and each minor series gets about a year of bug fixes and two years of security fixes after its first release. So a year of standing still adds roughly two hops to the eventual project, and once your series ages out of its security window, bug and security fixes become your own responsibility. One community guide on upgrade timing, Rails Fever, puts each major version’s practical support life at roughly three years and describes the far end of accumulation plainly: a 5.2-era app upgrading today is a months-scale project spanning multiple major jumps.

Two apps on the same version can face very different hops. In our experience, five factors explain most of the spread, and the first one matters most.

1. Test coverage. The official guide names good coverage as its precondition, and the warning underneath is blunt: without automated tests, you’re manually exercising every corner of the app after every hop, and that retesting comes to dominate the schedule. We hold client projects at 80-90% test coverage, and the payoff during an upgrade is that breakage shows up as red tests within the hour instead of as bug reports over the following month.

2. Front-end era. An app still building JavaScript through Webpacker owes a front-end migration at or before the 7.0-era hop, and in our experience that migration can cost more than the framework side of the upgrade. The migration only has to happen once, though; after that, later hops leave the front end alone.

3. Gem count, forks, and monkeypatches. Every gem in the Gemfile also has to clear the hop. Maintained gems usually have a compatible release waiting; each abandoned one turns into a replacement decision, and every fork or monkeypatch is a piece of archaeology, because someone has to rediscover why it exists before daring to touch it.

4. Ruby version distance. Rails versions set Ruby floors: 8.0 and 8.1 require Ruby 3.2 or newer, 7.2 requires 3.1, and the 7.0/7.1 series runs back to 2.7. The official guide recommends upgrading Ruby separately from Rails, Ruby first, and each Ruby bump wants its own deploy. An app behind on both is climbing two ladders, and the Ruby one adds real time to the plan.

5. Deploy and rollback muscle. Teams that can ship a small change safely, watch it in production, and roll it back with one command move faster through an upgrade, because an upgrade is that kind of deploy over and over. Teams that deploy rarely, or where only one person knows how, pay a caution tax on all of it.

The safe way to ship an upgrade sets the calendar, and it includes waiting on purpose. The framework bump deploys alone, with no feature work riding along. Then comes an error-watch window while the new version soaks under real traffic. Then the new framework defaults flip on one or two per deploy, each with its own soak, until the app runs the new configuration end to end. Our Rails 7 to 8 checklist is the run-sheet version of that rhythm.

That pacing looks slow on a roadmap, but it keeps every deploy small enough to reason about, and it’s how we deliver major Rails and Ruby upgrades with zero downtime: no single deploy ever carries enough change to take the site down, so there’s never a maintenance window to schedule. When you see a quarter of calendar wrapped around two weeks of effort, that usually means the upgrade is going well, because the gap is soak time you’d want anyway.

It’s worth triangulating against what others publish. The most data-rich source is FastRuby, a firm that specializes in Rails upgrades: their write-up on upgrade cost draws on more than 100 upgrade projects and 30,000-plus invested hours. They move one minor version at a time, the same path the official guide prescribes, and they measure engagements in weeks, where a week means two engineers at 30 hours each. The trend inside their data matches what you’d hope: the more recent the target version, the shorter the project, with 6.1 to 7.0 as the exception because bigger apps arrived at that jump and a required Ruby upgrade rode along with it. JetRockets’ upgrade service page states a typical timeline of 2 to 12 weeks depending on scope; that 6x spread is the factor list from the previous section showing up in someone else’s numbers. And Aha’s engineering write-up is the big-app data point: major upgrades of their large codebase take months, with the test-fixing stage alone running weeks to months, managed by dual-booting the app across two Rails versions.

Read all of it with the era in mind. FastRuby’s public dataset ends at the 6.1 to 7.0 bucket, and the hops since then have been markedly smaller. On a well-kept app the current hop can land in an afternoon, which no dataset that stops at the 7.0 jump would predict. If your app has been maintained, the published ranges probably read high for you.

Every runaway upgrade we’ve seen traces back to prep debt, and four conditions do most of the damage. No tests on the money paths means every hop needs manual verification end to end, which at upgrade scale is slower than writing the missing tests first. An end-of-life Ruby puts a whole second ladder in front of the Rails one. Abandoned and forked gems each demand a replacement decision that nobody has wanted to make for years, and single-person deploy knowledge forces the whole soak-and-ship rhythm through one person’s calendar. Any one of these can double a hop; with two or more, preparation dominates the schedule, and an estimate that only covers the upgrade itself misses the bulk of the work.

We’ve made the longer argument about why waiting makes each of these conditions more expensive in the economics of Rails maintenance, and our week-one codebase audit shows how we pin down the scope once an app is already in that spot.

This is an estimate you can build yourself, today, with the Gemfile and a coverage report open. Count the hops between your version and the target, score the five factors honestly, and you’ll have a range you can defend in a planning meeting. On a maintained app the arithmetic usually comes out smaller than the folklore suggests: a hop or two, about a week of effort each, wrapped in enough calendar to soak safely. If it comes out the other way, with several hops ahead and thin tests underneath, that’s worth knowing before anyone commits to a date, and it’s the case our Ruby on Rails work is built for: we start with an audit and turn what you’ve scored into a roadmap you can put dates against.