Skip to content

ombulabs/claude-code_rails-upgrade-skill / rails-upgrade

rails-upgrade

Verified

Analyzes Rails applications and generates comprehensive upgrade reports with breaking changes, deprecations, and step-by-step migration guides for Rails 2.3 through 8.1. Use when upgrading Rails applications, planning multi-hop upgrades, querying version-specific changes, or answering what stands between the app and the next Rails version. Based on FastRuby.io methodology and "The Complete Guide to Upgrade Rails" ebook.

FileKindSize
SKILL.mdskill md11.0 KB
detection-scripts/gem_limits.rbscript6.0 KB
detection-scripts/hop.rbscript2.2 KB
detection-scripts/patterns/rails-40-patterns.expectations.ymlconfig43.8 KB
detection-scripts/patterns/rails-40-patterns.ymlconfig96.5 KB
detection-scripts/patterns/rails-41-patterns.expectations.ymlconfig25.6 KB
detection-scripts/patterns/rails-41-patterns.ymlconfig59.8 KB
detection-scripts/patterns/rails-42-patterns.expectations.ymlconfig27.5 KB
detection-scripts/patterns/rails-42-patterns.ymlconfig48.7 KB
detection-scripts/patterns/rails-50-patterns.expectations.ymlconfig1.9 KB
detection-scripts/patterns/rails-50-patterns.ymlconfig8.1 KB
detection-scripts/patterns/rails-51-patterns.expectations.ymlconfig4.2 KB
detection-scripts/patterns/rails-51-patterns.ymlconfig15.0 KB
detection-scripts/patterns/rails-52-patterns.expectations.ymlconfig5.0 KB
detection-scripts/patterns/rails-52-patterns.ymlconfig14.7 KB
detection-scripts/patterns/rails-60-patterns.expectations.ymlconfig1007 B
detection-scripts/patterns/rails-60-patterns.ymlconfig14.2 KB
detection-scripts/patterns/rails-70-patterns.expectations.ymlconfig4.0 KB
detection-scripts/patterns/rails-70-patterns.ymlconfig11.2 KB
detection-scripts/patterns/rails-71-patterns.expectations.ymlconfig3.1 KB
detection-scripts/patterns/rails-71-patterns.ymlconfig9.5 KB
detection-scripts/patterns/rails-72-patterns.expectations.ymlconfig1.2 KB
detection-scripts/patterns/rails-72-patterns.ymlconfig6.1 KB
detection-scripts/patterns/rails-80-patterns.expectations.ymlconfig6.6 KB
detection-scripts/patterns/rails-80-patterns.ymlconfig21.2 KB
detection-scripts/patterns/rails-81-patterns.expectations.ymlconfig4.3 KB
detection-scripts/patterns/rails-81-patterns.ymlconfig13.2 KB
detection-scripts/scan_patterns.rbscript42.8 KB
examples/multi-hop-upgrade.mdmarkdown18.9 KB
examples/simple-upgrade.mdmarkdown4.0 KB
references/breaking-changes-by-version-reference.mdmarkdown3.9 KB
references/deprecation-warnings-reference.mdmarkdown10.7 KB
references/gem-compatibility-reference.mdmarkdown8.2 KB
references/js-compressor-sprockets-mismatch-reference.mdmarkdown4.7 KB
references/multi-hop-strategy-reference.mdmarkdown8.8 KB
references/next-hop-readiness-reference.mdmarkdown2.1 KB
references/no-test-suite-smoke-reference.mdmarkdown4.7 KB
references/request-patterns-reference.mdmarkdown3.7 KB
references/sequential-strategy-reference.mdmarkdown2.1 KB
references/staying-current-reference.mdmarkdown7.8 KB
references/testing-checklist-reference.mdmarkdown6.3 KB
templates/app-update-preview-template.mdmarkdown4.3 KB
templates/upgrade-report-template.mdmarkdown10.2 KB
version-guides/upgrade-3.2-to-4.0.mdmarkdown68.0 KB
version-guides/upgrade-4.0-to-4.1.mdmarkdown66.7 KB
version-guides/upgrade-4.1-to-4.2.mdmarkdown60.7 KB
version-guides/upgrade-4.2-to-5.0.mdmarkdown9.7 KB
version-guides/upgrade-5.0-to-5.1.mdmarkdown19.1 KB
version-guides/upgrade-5.1-to-5.2.mdmarkdown17.7 KB
version-guides/upgrade-5.2-to-6.0.mdmarkdown6.4 KB
version-guides/upgrade-6.0-to-6.1.mdmarkdown6.8 KB
version-guides/upgrade-6.1-to-7.0.mdmarkdown14.7 KB
version-guides/upgrade-7.0-to-7.1.mdmarkdown13.2 KB
version-guides/upgrade-7.1-to-7.2.mdmarkdown11.2 KB
version-guides/upgrade-7.2-to-8.0.mdmarkdown23.1 KB
version-guides/upgrade-8.0-to-8.1.mdmarkdown14.0 KB
workflows/00-verify-latest-patch-workflow.mdmarkdown1.7 KB
workflows/01-run-test-suite-workflow.mdmarkdown12.7 KB
workflows/02-resolve-deprecation-warnings-workflow.mdmarkdown6.3 KB
workflows/03-validate-upgrade-path-workflow.mdmarkdown1.8 KB
workflows/04-setup-next-rails-workflow.mdmarkdown1.5 KB
workflows/05-detect-breaking-changes-workflow.mdmarkdown20.0 KB
workflows/06-check-gem-compatibility-workflow.mdmarkdown11.1 KB
workflows/07-boot-smoke-test-workflow.mdmarkdown7.3 KB
workflows/08-generate-upgrade-report-workflow.mdmarkdown12.7 KB
workflows/09-generate-app-update-preview-workflow.mdmarkdown7.3 KB
workflows/10-implement-and-upgrade-workflow.mdmarkdown2.5 KB
workflows/11-sync-ci-workflow.mdmarkdown8.6 KB
workflows/12-align-load-defaults-workflow.mdmarkdown952 B
workflows/13-mention-cleanup-workflow.mdmarkdown1.3 KB

references/gem-compatibility-reference.md

View on GitHub
# Gem Compatibility Reference

**When to read this:** Workflow 06's compatibility check returned at least one blocker (a gem with no released version that supports the target Rails). This file is the playbook for resolving those.

For the compatibility check itself, see Workflow 06 (primary: `next_rails` `bundle_report compatibility`; secondary: `workflows/06-check-gem-compatibility-workflow.md`). Don't load this file unless you're already past the check and have blockers to work through.

This file used to carry static `gem × Rails-version` lookup tables. They drifted out of date and ignored the user's actual lockfile, so they were removed in favor of the live checks.

---

## Update order

When applying the bumps the compatibility check produced:

1. **Ruby** — meet the target Rails version's minimum.
2. **Rails** — update to the target version.
3. **Auth / authorization gems** — `devise`, `pundit`, `cancancan`, `doorkeeper`. Boot-blocking when wrong.
4. **Testing gems** — `rspec-rails`, `factory_bot_rails`, `capybara`, `shoulda-matchers`. Required to validate the upgrade.
5. **Everything else** — incrementally, one gem at a time (`bundle update <gem> --conservative`).

The compatibility check tells you the minimum target for each gem. Use it to decide which gems can stay on their current version and which need an explicit bump.

---

## Playbook: gem has no compatible version

When `bundle_report` lists a gem under "with no new compatible versions" or "with no new versions", or railsbump returns `incompatible` with no `earliest_compatible_version`, you have a blocker. Options, in order of preference:

1. **Look for a maintained fork** that adds Rails support — search GitHub for "fork of <gem>" with the target Rails in recent commits.
2. **Check the gem's open PRs / issues** for in-flight Rails support. If a PR is close to merging, ask the user whether to vendor the branch as a temporary `git:` source.
3. **Wait for an upstream release** if the gem is actively maintained and the next release is imminent.
4. **Switch to an alternative** when the gem is abandoned, OR when a Rails-removed API has a back-compat gem and you'd rather use it than refactor. Examples:
   - `paperclip` → `shrine` / Active Storage (paperclip is abandoned).
   - When moving Rails 3 → 4, `attr_accessible` was removed from core. Two paths: refactor controllers to strong parameters, OR add `protected_attributes` to keep `attr_accessible` working. The shim is a valid choice when the controller surface is large and the upgrade timeline is tight; refactoring later is still possible.
5. **Fork and patch** as a last resort. Document the fork in the Gemfile and open an upstream PR.

Surface the choice to the user — do not silently swap gems. Each option has a different long-term cost.

A common false-blocker pattern: gems that became unnecessary in a specific Rails release. They show up under "with no new versions" in `bundle_report`, but the fix is to remove them, not to find a compatible version.

- **Merged into Rails core**: `strong_parameters` was extracted from Rails 3.x as a backport, and is built into Rails ≥ 4.0 (`ActionController::Parameters`). Just remove the gem when targeting Rails 4 or newer.
- **Replaced by core / a successor gem**: `turbo-sprockets-rails3` is replaced by `sprockets-rails` in Rails 4. `paperclip` is unmaintained and replaced by Active Storage / Shrine.
- **Extracted as a back-compat shim**: `protected_attributes` is the *opposite* shape — it was extracted from Rails 4.0 specifically as a transitional shim for the old mass-assignment API and was never re-merged. It still exists as a separate gem, but if your code is moving to `strong_parameters` you can remove it once the controllers are converted.

If `bundle_report` flags one of these, check the target version guide before assuming you need a fork.

---

## Known Gotchas

Real issues hit during actual upgrades, not generic advice. Add to this list as new ones surface.

### `concurrent-ruby` >= 1.3.5 breaks Rails' logger require order on Ruby < 3.5

**Symptom:** `NameError: uninitialized constant ActiveSupport::LoggerThreadSafeLevel::Logger`, raised from `active_support/logger_thread_safe_level.rb` on boot. `bundle install` / `bundle_report` show nothing wrong — this is a pure require-order bug, not a version constraint conflict.

**Cause:** `activesupport/lib/active_support/logger.rb` requires `active_support/logger_thread_safe_level` *before* it requires the stdlib `logger` gem. Versions of `logger_thread_safe_level.rb` prior to the fix reference the bare `Logger` constant without requiring it themselves, relying on something else in the load path having already pulled in `logger` — which `concurrent-ruby` < 1.3.5 happened to do as a side effect, and 1.3.5+ no longer does.

**Confirmed via source diff:** `activesupport/lib/active_support/logger_thread_safe_level.rb` at tags `v6.1.7.10` and `v7.0.8.7` has no `require "logger"` at the top (only `require "concurrent"` and `require "fiber"`) — vulnerable. The same file at `v7.0.10` and `v7.1.6` adds an explicit `require "logger"` — fixed. **The fix is per-Rails-patch-release, not per-Rails-minor** — check the specific patch you're on, not just the major.minor. A 7.0.x app can be on either side of the line. All four tags checked directly against GitHub source.

**Fix:** Pin `gem "concurrent-ruby", "< 1.3.5"` in the Gemfile. Safe to apply unconditionally across a dual-boot Gemfile (both sides) even if only the older side actually needs it — confirmed empirically that Rails 7.0.10 boots fine with either the pin or `concurrent-ruby` 1.3.7.

**How to verify whether your target Rails patch needs the pin:** `curl -s https://raw.githubusercontent.com/rails/rails/v<VERSION>/activesupport/lib/active_support/logger_thread_safe_level.rb | head -10` and check for `require "logger"` near the top.

### Accidentally narrow legacy Gemfile pins

Distinct from "gem has no compatible version" above: these are gems where a *compatible* version genuinely exists, but the app's own Gemfile pins below it — usually a leftover constraint from years earlier that nobody has revisited. `bundle_report` may not flag these clearly since the gem itself isn't the blocker; the app's own version constraint is. Bundler's resolver error will look like a normal dependency conflict, e.g.:

```
font-awesome-rails was resolved to 4.7.0.7, which depends on
  railties (>= 3.2, < 7)
```

Check the Gemfile for pins that predate the target Rails version's release by years — `~> 1.8.2` on a gem now at `1.15.x`, an unpinned gem still resolving to a several-years-old version because nothing forced a re-resolve. Bump the floor (`bundle lock --update <gem>`) rather than assuming it's a real blocker requiring a fork/replace.

Real example (6.1 -> 7.0): `nokogiri "~> 1.8.2"` (pinned circa 2018) blocked resolution once `loofah`/`rails-html-sanitizer` needed a newer `nokogiri` for Rails 7.0. `font-awesome-rails` (unpinned, but locked at `4.7.0.7` since nothing had bumped it) capped `railties < 7`; `4.7.0.9` relaxed that to `< 9.0`. Neither gem was actually incompatible with Rails 7.0 — the lockfile just hadn't moved in years.

### Dev-only gems with an independent Ruby floor

When a gem's Rails-N-compatible release also raises its own Ruby floor higher than the Ruby version this specific hop targets, and the gem is dev/test-only (doesn't affect production boot or the test suite itself), the pragmatic move is usually to drop it for this hop rather than force an unplanned Ruby bump — Ruby upgrades are their own separate, independently-sequenced piece of work.

Real example (6.1 -> 7.0, staying on Ruby 2.7.2): `spring` 2.x (Rails-6-era) works fine on Ruby 2.7, but `spring-watcher-listen` 2.1.0 requires `spring >= 4`, and `spring` 4.x requires Ruby >= 3.1. Since `spring` is dev-only tooling (faster local boot times, not loaded in CI or by the deployed app), the resolution was to drop `spring` / `spring-watcher-listen` from the Gemfile's `next?` (target-Rails) branch entirely, with a comment noting they come back once Ruby is separately upgraded past 3.1. Confirm a gem is safe to drop this way by checking it's declared only inside `group :development` (or `:development, :test`) and isn't required by any file the test suite or production boot path loads.
planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies.Stars: 108kUpdated Claude CodeCodexVerifiedInstall
meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要".Stars: 108kUpdated Claude CodeCodexVerifiedInstall