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

templates/upgrade-report-template.md

View on GitHub
# Rails {FROM} → {TO} Upgrade Report

- **Generated:** {DATE}
- **Project:** {PROJECT_NAME}
- **Current version:** {FROM_FULL}, latest patch of its series
- **Target version:** {TO_FULL}
- **Dual-boot:** `Gemfile.next` resolves {TO_FULL}; the default `Gemfile` stays on {FROM_FULL} until the pin changes (see the plan)
- **Changes made while producing this report:** {TREE_CHANGES}
<!-- e.g. "Gemfile: next_rails gem and if next? branch added; Gemfile.lock and Gemfile.next.lock re-resolved. Uncommitted." or "none" -->

---

## Executive Summary

| | Count |
|--|-------|
| 🛑 Fix before bump | {FIX_BEFORE_COUNT} |
| 📅 Fix when ready | {FIX_WHEN_READY_COUNT} |
| Deprecation warnings on {FROM}: fixed / deferred | {DEP_FIXED} / {DEP_DEFERRED} |
| Deprecation warnings emitted by {TO} at boot or in the suite | {TARGET_DEP_COUNT} |
| Gems: required bumps / blockers / already compatible | {GEM_BUMPS} / {GEM_BLOCKER_COUNT} / {GEM_OK} |
| Boot under `Gemfile.next` | {BOOT_RESULT} |
| Test suite under `Gemfile.next` | {NEXT_SUITE_RESULT} |
<!-- NEXT_SUITE_RESULT names every suite that ran: unit and system for Minitest apps, the spec suite for RSpec -->

- **Baseline on {FROM_FULL}:** {TEST_COUNT} tests, {ASSERTION_COUNT} assertions, {FAILURE_COUNT} failures.
- **Patterns checked:** {PATTERNS_CHECKED} for this hop; {PATTERNS_FIRED} matched (see Detection Patterns below).

{ONE_PARAGRAPH_SUMMARY}
<!-- Three or four plain sentences: how big this hop is for this app, where the findings come from, what kind of work remains. Written for someone who reads nothing else. -->

**Contents:** What Was Checked (deprecations, detection patterns, gems, boot and tests) · Fix Before Bump · Fix When Ready · Plan · Testing Checklist · Rollback Plan

---

## What Was Checked

The four checks below run before any finding is written. Anything they turn up that needs work is an entry in Fix Before Bump; these sections record what was checked and what came back.

### Deprecation Warnings on {FROM}

The warnings the current version emits, collected before any dual-boot work.

| Warning | Count | Status | Note |
|---------|-------|--------|------|
{DEPRECATION_INVENTORY_ROWS}
<!-- Status: fixed (already in the baseline above) / deferred to the bump (setter removed on {TO}; also listed in Fix Before Bump) / deferred to a later hop (about a version after {TO}) / gem-owned (belongs to the gem's own update) -->

---

### Detection Patterns

{PATTERNS_CHECKED} patterns for the {FROM} to {TO} hop were run against the codebase; {PATTERNS_FIRED} matched. Each match is an entry in Fix Before Bump or Fix When Ready below.

| Pattern | Kind | Priority | Sites | Files |
|---------|------|----------|-------|-------|
{PATTERN_SCAN_ROWS}
<!-- One row per pattern that matched, same order as the entries below. Sites: the kept count, plus "(N dropped as false positives)" when any were. When none matched, replace the table with "No pattern matched." When the scanner did not run, say how the patterns were searched instead (for example "searched line by line with grep; calls split across lines may be missed"). -->

- Could not be scanned (no files at their paths in this app): {PATTERNS_NOT_SCANNED}.
- Every site dropped by the pattern's own exclusion: {PATTERNS_ALL_SUPPRESSED}.
<!-- Write "none" when a list is empty. For each name listed, say what was done: checked by hand, not applicable, or still open. -->

---

### Gem Compatibility

Check used: {GEM_CHECK_USED}.
<!-- "next_rails bundle_report compatibility", "railsbump", or "not run: <reason>" -->

{GEM_SUMMARY}
<!-- When nothing changes: "All {GEM_OK} direct gems already declare support for {TO}. Blockers: none." and omit the table below entirely, header included.
     Otherwise keep the table, one row per gem that needs a bump or has no compatible release. -->

| Gem | Locked | Needed for {TO} | Bucket |
|-----|--------|-----------------|--------|
{GEM_ROWS}

Blockers (no released version supports {TO}): {GEM_BLOCKER_LIST}.

---

### Boot and Tests Under `Gemfile.next`

```
{BOOT_SMOKE_BLOCK}
```

Suite under `Gemfile.next`: {NEXT_SUITE_RESULT}. Deprecation warnings {TO} emitted during boot or the suite: {TARGET_DEP_COUNT}; each one is a Fix Before Bump entry below. Test failures, if any, are Fix Before Bump entries too.

---

---

## 🛑 Fix Before Bump ({FIX_BEFORE_COUNT})

Everything that raises, fails to boot, or warns on {TO} about behavior that changes there. All of it lands before the default `Gemfile` moves to {TO}. Ordered HIGH → MEDIUM → LOW. Sources: the pattern catalog, the deprecation warnings {TO} emitted at boot or in the suite, the gem bumps the boot check needed, the test failures under `Gemfile.next`, and the current-version fixes deferred because their setter is removed on {TO}.

<!-- Repeat this block for each finding -->

### {ISSUE_NAME}

**Kind:** `{KIND}` · **Priority:** {PRIORITY} · **Found:** {COUNT} occurrence(s) · **How found:** {HOW_FOUND}
<!-- HOW_FOUND: "pattern catalog", "warning at boot under Gemfile.next", "warning in the suite under Gemfile.next", "test failure under Gemfile.next", "gem compatibility check", "deferred from the current-version deprecation pass", "manual review of the version guide or the target Rails source" -->

**Affected files:**
{FILE_LIST}
<!-- When the cause is an absent line (for example no config.load_defaults at all), write "no line sets this; the {FROM} default applies" and name the file where the line belongs -->

**What changes in Rails {TO}:** {EXPLANATION}

**Your code (before):**
```ruby
# {FILE_PATH}:{LINE_NUMBER}
{ACTUAL_CODE}
```
<!-- For an absent line: show the surrounding block and a comment "# nothing here sets <key>".
     Redact secret values (keys, tokens, passwords, anything read from ENV or a secrets/credentials file): keep the key name, replace the value with <redacted>. -->

**Change (after):**
```ruby
{FIXED_CODE}
```

{DUAL_BOOT_NOTE}
<!-- DUAL_BOOT_NOTE is one of:
     - nothing, when the new form works on both Rails versions (the usual case: a direct rewrite)
     - "Two-sided: the new API does not exist on {FROM}. Branch with `NextRails.next?` (target form on top, current form below) and drop the branch at cleanup."
     - "Setter removed on {TO}: apply it as the default pin changes, not before." -->

{CUSTOM_CODE_WARNING}
<!-- "⚠ïļ Custom code: <file> <what it does> <why it interacts with this change>", only when detected -->

<!-- End repeat block -->

---

## 📅 Fix When Ready ({FIX_WHEN_READY_COUNT})

Silent and working on {TO}; recommended, not tied to the bump. Do them whenever the team chooses, before or after the pin changes. The one timing rule: entries marked `migration` become warnings or removals at a later hop, so finishing them before the next hop starts avoids doing them under pressure. Same block shape as above; entries found by hand (a Gemfile line the target no longer needs, a config key with a better default) belong here too.

{FIX_WHEN_READY_BLOCKS}
<!-- When empty: "None. All {PATTERNS_CHECKED} patterns for this hop were searched." -->

---

## Plan

The analysis is done; this is what remains, in order. How the work is split into branches and pull requests is the team's call.

### Fix before bump
- [ ] Every 🛑 entry above, on both sides of the dual-boot. Direct rewrite unless the entry says two-sided
- [ ] Suite green on `Gemfile` and on `Gemfile.next`
{BREAKING_CHANGE_TASKS}

### Bump the default pin
- [ ] Database backup taken and a restore tested
- [ ] `Gemfile`: change the `else` branch's pin to {TO_FULL} so both sides resolve {TO}; leave the `if next?` / `else` structure, `Gemfile.next` and `Gemfile.next.lock` in place until cleanup
- [ ] `bundle install` for both lockfiles; suite green on both
- [ ] Configuration: apply the app:update preview (deliverable 2) file by file on the {TO} side; do not run `rails app:update` blind. Keys that do not exist on {FROM} go under a `NextRails.next?` guard until cleanup
- [ ] Do not change `config.load_defaults` yet (see below)
- [ ] CI configuration matches the upgraded Gemfile: Ruby version, Rails matrix, service versions
- [ ] Deploy and verify

### Fix when ready
- [ ] The 📅 entries, at the team's pace

### Align `load_defaults`
- [ ] After the bump ships and is stable, move `config.load_defaults` to {TO} one setting at a time, running the suite between settings

### Cleanup
- [ ] When the team is ready and not heading straight into the next hop: remove the `NextRails.next?` branches, the `if next?` / `else` structure and `Gemfile.next`

---

## Testing Checklist

Run after the fix-before-bump work and again after the default pin changes. Tailor the manual list to this app's routes, mailers and jobs; drop what it does not have.

- [ ] Unit, controller, integration and system tests green on both Gemfiles
- [ ] {MANUAL_CHECKS}
- [ ] Boot time and request times comparable to {FROM}; no new N+1

---

## Rollback Plan

Dual-boot is the rollback: the {FROM} side stays intact until cleanup.

- Before the default pin changes: nothing to roll back; the default side never moved.
- After the default pin changes: set the `else` branch's pin back to {FROM_FULL}, `bundle install`, redeploy. Roll back migrations only if {TO} added any (`rails db:rollback STEP=N`).
- Cache: `bin/rails runner 'Rails.cache.clear'` and `rails tmp:clear` if the cache format version changed.
- Database: restore the backup taken before the pin change only if data changed shape.

---

## Post-Upgrade Tasks

- [ ] CI configuration reviewed and attached to the upgrade pull request
- [ ] Deployment scripts and Dockerfile on the new Ruby / Rails pins
- [ ] Team notified; error rates and performance watched after deploy

---

## Resources

- [Rails {TO} Release Notes](https://guides.rubyonrails.org/{TO_UNDERSCORE}_release_notes.html)
- [Rails Upgrade Guide](https://guides.rubyonrails.org/upgrading_ruby_on_rails.html)
- [FastRuby.io Rails Upgrade Blog](https://www.fastruby.io/blog)

---

## Next Steps

1. Review this report; the app:update preview is deliverable 2
2. Start with the HIGH entries under Fix Before Bump
3. Run both suites after each change

---

**Report generated by Rails Upgrade Assistant**, built on the [FastRuby.io](https://www.fastruby.io) upgrade methodology. Want a team that does this every week to take the hop from here? [Talk to FastRuby.io](https://www.fastruby.io/contact).
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