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

version-guides/upgrade-6.1-to-7.0.md

View on GitHub
# Rails 6.1 → 7.0 Upgrade Guide

**Ruby Requirement:** 2.7.0+ (3.0+ recommended)

---

## Overview

Rails 7.0 is a major release focused on frontend modernization:
- **Hotwire** (Turbo + Stimulus) replaces Turbolinks + UJS
- **Import Maps** as default JavaScript solution
- **Webpacker removed** from default stack
- **Encrypted attributes** by default
- **Zeitwerk mode only** (classic autoloader removed)

---

## Breaking Changes

### ðŸ”ī HIGH PRIORITY

#### Ruby 2.7+ Required

**Pattern:** `RUBY_VERSION`

**What Changed:**
Rails 7.0 requires Ruby 2.7.0 or newer: the `rails` 7.0 gemspec sets `required_ruby_version >= 2.7.0`, while 6.1 accepts `>= 2.5.0`. Bundler refuses to install 7.0 on an older Ruby, so upgrade Ruby first, while the app is still on Rails 6.1, as its own deploy. Rails 7.0.0 itself needs Ruby below 3.1 ([FastRuby.io compatibility table](https://www.fastruby.io/blog/ruby/rails/versions/compatibility-table.html)); on Ruby 3.1 or newer, use 7.0.1 or a later 7.0 patch. The gemspec sets no upper bound; a Ruby released after a Rails version may need that version's latest patch release.

**Detection Pattern:**
```ruby
# Gemfile
ruby "2.6.10"

# .ruby-version
2.6.10

# .tool-versions
ruby 2.6.10
```

**Fix:**
```bash
# Update Ruby first
rbenv install 3.1.4
rbenv local 3.1.4
```

---

#### Webpacker → Import Maps / jsbundling-rails

**Pattern:** `WEBPACKER`

**What Changed:**
Webpacker is no longer the default. Choose:
- **Import Maps** (default) - No bundling, native ES modules
- **jsbundling-rails** - Use esbuild, rollup, or webpack
- **Keep Webpacker** - Still works but not maintained

**Detection Pattern:**
```ruby
# Gemfile
gem 'webpacker'

# Views
<%= javascript_pack_tag 'application' %>
```

**Migration Options:**

**Option A: Import Maps (Simplest)**
```bash
rails importmap:install
```

```erb
<!-- BEFORE (Webpacker) -->
<%= javascript_pack_tag 'application' %>

<!-- AFTER (Import Maps) -->
<%= javascript_importmap_tags %>
```

**Option B: jsbundling-rails (esbuild)**
```bash
rails javascript:install:esbuild
```

```erb
<!-- BEFORE (Webpacker) -->
<%= javascript_pack_tag 'application' %>

<!-- AFTER (jsbundling) -->
<%= javascript_include_tag 'application', 'data-turbo-track': 'reload' %>
```

---

#### Turbolinks → Turbo

**Pattern:** `TURBOLINKS`

**What Changed:**
Turbolinks is replaced by Turbo (part of Hotwire).

**Detection Pattern:**
```ruby
# Gemfile
gem 'turbolinks'

# JavaScript
import Turbolinks from 'turbolinks'
Turbolinks.start()
```

**Fix:**
```ruby
# Gemfile
gem 'turbo-rails'
```

```javascript
// BEFORE
import Turbolinks from 'turbolinks'
Turbolinks.start()

// AFTER
import "@hotwired/turbo-rails"
```

**Event Changes:**
```javascript
// BEFORE (Turbolinks)
document.addEventListener('turbolinks:load', function() {
  // code
})

// AFTER (Turbo)
document.addEventListener('turbo:load', function() {
  // code
})
```

| Turbolinks Event | Turbo Event |
|-----------------|-------------|
| turbolinks:load | turbo:load |
| turbolinks:click | turbo:click |
| turbolinks:before-visit | turbo:before-visit |
| turbolinks:visit | turbo:visit |
| turbolinks:before-render | turbo:before-render |
| turbolinks:render | turbo:render |

---

#### Rails UJS → Turbo / Stimulus

**Pattern:** `RAILS_UJS`

**What Changed:**
`rails-ujs` functionality is now handled by Turbo and Stimulus.

**Detection Pattern:**
```javascript
import Rails from '@rails/ujs'
Rails.start()
```

```erb
<%= link_to 'Delete', item, method: :delete %>
<%= link_to 'Delete', item, data: { confirm: 'Sure?' } %>
```

**Fix:**

```erb
<!-- BEFORE (UJS) -->
<%= link_to 'Delete', item, method: :delete %>

<!-- AFTER (Turbo) -->
<%= button_to 'Delete', item, method: :delete %>
<!-- or -->
<%= link_to 'Delete', item, data: { turbo_method: :delete } %>
```

```erb
<!-- BEFORE (UJS confirm) -->
<%= link_to 'Delete', item, data: { confirm: 'Sure?' } %>

<!-- AFTER (Turbo confirm) -->
<%= link_to 'Delete', item, data: { turbo_confirm: 'Sure?' } %>
```

---

Remove `@rails/ujs` (and `rails-ujs`) completely once Turbo is in; with both loaded, forms submit twice.


#### form_with Remote Behavior Change

**Pattern:** `FORM_WITH_LOCAL`

**What Changed:**
`form_with` now submits forms with Turbo (remote by default).

**Detection Pattern:**
```erb
<%= form_with model: @item, local: true do |f| %>
```

**Fix:**
```erb
<!-- BEFORE (explicit local: true) -->
<%= form_with model: @item, local: true do |f| %>

<!-- AFTER (Turbo handles everything) -->
<%= form_with model: @item do |f| %>

<!-- To disable Turbo on a form -->
<%= form_with model: @item, data: { turbo: false } do |f| %>
```

---

### ðŸŸĄ MEDIUM PRIORITY

#### secrets.yml → credentials

**Pattern:** `SECRETS_YML`

**What Changed:**
`Rails.application.secrets` is deprecated.

**Detection Pattern:**
```ruby
Rails.application.secrets.secret_key
```

**Fix:**
```ruby
# BEFORE
Rails.application.secrets.api_key

# AFTER
Rails.application.credentials.api_key

# Or with dig for nested values
Rails.application.credentials.dig(:aws, :access_key_id)
```

**Migration:**
```bash
# Edit credentials
rails credentials:edit

# For environment-specific
rails credentials:edit --environment production
```

---

#### Enum Syntax Changes

**Pattern:** `ENUM_SYNTAX`

**What Changed:**
New enum syntax available (hash form preferred).

**Fix:**
```ruby
# BEFORE (still works)
enum status: [:draft, :published, :archived]

# AFTER (preferred)
enum status: { draft: 0, published: 1, archived: 2 }

# With options
enum :status, { draft: 0, published: 1 }, prefix: true
```

---

#### image_tag skip_pipeline Removed

**Pattern:** `IMAGE_TAG_PIPELINE`

**What Changed:**
`skip_pipeline` option removed from `image_tag`.

**Fix:**
```erb
<!-- BEFORE -->
<%= image_tag 'logo.png', skip_pipeline: true %>

<!-- AFTER -->
<%= image_tag 'logo.png' %>
```

---

#### to_s(:format) Deprecated

**Pattern:** `TO_S_FORMAT`

**What Changed:**
`to_s(:format)` is deprecated in favor of `to_fs(:format)`.

**Detection Pattern:**
```ruby
date.to_s(:short)
time.to_s(:db)
```

**Fix:**
```ruby
# BEFORE
Date.today.to_s(:short)

# AFTER
Date.today.to_fs(:short)
```

---

#### redirect_to Open Redirect Protection

**Pattern:** `OPEN_REDIRECT_PROTECTION`

**What Changed:**
`load_defaults 7.0` sets `config.action_controller.raise_on_open_redirects = true`. With it on, `redirect_to` and `redirect_back_or_to` to a host different from the current one raise `ActionController::Redirecting::UnsafeRedirectError` instead of redirecting. This is not a deprecation, there is no warning phase, and it is gated by `load_defaults 7.0`, so an app only sees it once `load_defaults` reaches 7.0, which is often a later hop than the Rails 7.0 bump itself. Internal path/url helpers and model records are unaffected; only dynamic or external destinations break.

**Detection Pattern:**
```ruby
redirect_to params[:return_to]
redirect_back_or_to session[:forward_url]
redirect_to request.referer
redirect_to "https://example.com"
```

**Fix:**
```ruby
# BEFORE (raises UnsafeRedirectError under load_defaults 7.0)
redirect_to "https://example.com"

# AFTER: allow the external host explicitly
redirect_to "https://example.com", allow_other_host: true
```

For destinations built from untrusted input, validate against an allowlist before allowing the external host. Passing `allow_other_host: true` on a raw `params`/`session`/`request.referer` value defeats the protection:

```ruby
# BEFORE (open redirect vulnerability if left unchecked)
redirect_to params[:return_to]

# AFTER: keep it internal, or validate before allowing other hosts
redirect_to params[:return_to], allow_other_host: false
# or rewrite an internal target as a path helper so no flag is needed
redirect_to safe_path_for(params[:return_to])
```

If you are not ready to audit every call site at this hop, you can keep the old behavior by leaving `config.action_controller.raise_on_open_redirects = false` in `config/application.rb`, then adopt it later. See the `rails-load-defaults` skill for the incremental `load_defaults` walkthrough.

---

#### Explicit Format/Handler Extension in `template:` / `layout:`

**Pattern:** `EXPLICIT_TEMPLATE_EXTENSION`

**What Changed:**
Passing a template name containing a `.` — `render template: "posts/show.html.erb"`, `layout: "pdf.html"` — worked on 6.1 and raises `ActionView::MissingTemplate` on 7.0.

6.1 tolerated it and said so: `actionview/lib/action_view/template/resolver.rb` warned `"Rendering actions with '.' in the name is deprecated"` from `find_template_paths_from_details`. That code path is gone in 7.0, so the dotted name is now taken literally and matches no template.

Most commonly hit through `wicked_pdf`'s `render pdf:` helper, which forwards `:template` / `:layout` straight through.

**Detection Pattern:**
```ruby
render template: "posts/show.html.erb"
render pdf: "report", template: "reports/show.html.erb", layout: "pdf.html"
```

**Fix:**
```ruby
# BEFORE
render template: "posts/show.html.erb"
render pdf: "report", layout: "pdf.html"

# AFTER
render template: "posts/show"
render pdf: "report", layout: "pdf"
```

**A sibling bug the regex cannot find.** If the render runs inside a non-html `respond_to` block and passes no explicit `formats:`, 7.0 resolves the template using the *block's* format instead of `:html` and raises `MissingTemplate` even with a bare template name. 6.1 fell back to `:html` here; 7.0 does not.

```ruby
respond_to do |format|
  format.pdf { render pdf: "report", template: "reports/show", formats: [:html] }
end
```

Neither a boot smoke test nor a green suite catches this one: it only manifests when that specific action + format combination is actually invoked. Exercise every non-`format.html` branch by hand or add a spec for it.

---

#### Active Storage `variant(resize:)` Under vips

**Pattern:** `ACTIVE_STORAGE_VARIANT`

**What Changed:**
`load_defaults 7.0` sets `config.active_storage.variant_processor = :vips`; below that the processor stays `:mini_magick`. `resize:` is not one of the image_processing macros, so under vips it is passed straight to libvips, which does not understand ImageMagick geometry strings like `"100x100>"`. Variants that worked on 6.1 then fail when they are generated.

**Detection Pattern:**
```ruby
user.avatar.variant(resize: "100x100>")
```

**Fix:**
```ruby
# BEFORE
user.avatar.variant(resize: "100x100>")

# AFTER
user.avatar.variant(resize_to_limit: [100, 100])
```
The AFTER works on 6.1 too, with either processor. To keep ImageMagick after `load_defaults 7.0` instead, set `config.active_storage.variant_processor = :mini_magick`.

---

### ðŸŸĒ LOW PRIORITY

#### Spring Dropped From New Apps

**Pattern:** `SPRING`

**What Changed:**
The 7.0 app template leaves `gem "spring"` commented out, so new apps no longer get it. An app that keeps Spring needs spring 4.0 or later: 4.0.0 is the first release whose README lists Rails 7.0 (3.x stops at 6.0), and it requires Rails 6.0 or later.

**Detection Pattern:**
```ruby
gem "spring"
```

**Fix:**
```ruby
# BEFORE (Gemfile)
gem "spring", "~> 2.1"

# AFTER: bump it, or remove spring and bin/spring
gem "spring", ">= 4.0"
```
The AFTER works on 6.1 as well, so no `NextRails.next?` branch is needed. Spring 3.0 and later raise unless `config.cache_classes = false` in each environment Spring runs.

---

#### `urlsafe_csrf_tokens` Setting Deprecated

**Pattern:** `URLSAFE_CSRF_TOKENS`

**What Changed:**
Rails 7.0 makes URL-safe CSRF tokens the default and deprecates `config.action_controller.urlsafe_csrf_tokens`: assigning it warns for `true` ("URL-safe CSRF tokens are now the default") and for `false` ("Non-URL-safe CSRF tokens are deprecated"). An app on `load_defaults` below 6.1 gets the `false` warning with no line of its own, because `load_defaults 5.0` sets it. Rails 7.1 removes the setting. Nothing breaks during a rolling deploy: 7.0 still decodes the tokens a 6.1 server issued.

**Detection Pattern:**
```ruby
# config/application.rb or config/initializers/new_framework_defaults_6_1.rb
config.action_controller.urlsafe_csrf_tokens = true
```

**Fix:**
```ruby
# BEFORE
config.action_controller.urlsafe_csrf_tokens = true

# AFTER (keep it on the 6.1 side only)
config.action_controller.urlsafe_csrf_tokens = true unless NextRails.next?
```

On `load_defaults` below 6.1, moving to 6.1 defaults or above also stops the warning.

---

## Migration Steps

### Phase 1: Preparation
```bash
git checkout -b rails-70-upgrade

# Upgrade Ruby first
rbenv install 3.1.4
rbenv local 3.1.4
```

### Phase 2: Gemfile Updates
```ruby
# Gemfile
gem 'rails', '~> 7.0.0'

# Remove
# gem 'webpacker'
# gem 'turbolinks'
# gem 'rails-ujs'  (if standalone)

# Add
gem 'turbo-rails'
gem 'stimulus-rails'
gem 'importmap-rails'  # or jsbundling-rails
```

```bash
bundle update rails
rails turbo:install stimulus:install importmap:install
```

### Phase 3: Frontend Migration
1. Update JavaScript imports
2. Replace Turbolinks events with Turbo events
3. Update UJS patterns (method: :delete, confirm:)
4. Test all forms and links

### Phase 4: Configuration
```bash
rails app:update
```

Update `config/application.rb`:
```ruby
config.load_defaults 7.0
```

### Phase 5: Testing
- Test all form submissions
- Test delete links
- Test JavaScript interactions
- Verify Turbo frame/stream features

---

## Turbo Migration Checklist

- [ ] Remove turbolinks gem
- [ ] Add turbo-rails gem
- [ ] Update JavaScript imports
- [ ] Replace event listeners (turbolinks:* → turbo:*)
- [ ] Update method: :delete links
- [ ] Update data-confirm to data-turbo-confirm
- [ ] Remove remote: true (Turbo handles this)
- [ ] Test form submissions
- [ ] Test link navigation

---

## Common Issues — Quick Reference

Error → section lookup for the most common errors encountered during this upgrade:

| Error | See |
|-------|-----|
| `ActionView::MissingTemplate` on an action that worked on 6.1 | "Explicit Format/Handler Extension in `template:` / `layout:`" — drop the `.html.erb` extension, pass `formats: [:html]` in non-html branches |
| `method: :delete` links send GET | "Rails UJS → Turbo / Stimulus" — `button_to` or `data-turbo-method` |
| Forms submit twice | "Rails UJS → Turbo / Stimulus" — remove rails-ujs completely |
| JavaScript not loading | "Webpacker → Import Maps / jsbundling-rails" — `<%= javascript_importmap_tags %>` |
| Variant images fail to generate after `load_defaults 7.0` | "Active Storage `variant(resize:)` Under vips" — use `resize_to_limit:` / `resize_to_fill:` |

---

## Gem Compatibility

| Gem | Minimum Version |
|-----|-----------------|
| devise | 4.8.0 |
| cancancan | 3.3.0 |
| sidekiq | 6.0.0 |
| rspec-rails | 5.0.0 |
| capybara | 3.36.0 |

---

## Resources

- [Rails 7.0 Release Notes](https://guides.rubyonrails.org/7_0_release_notes.html)
- [Hotwire Documentation](https://hotwired.dev)
- [Turbo Handbook](https://turbo.hotwired.dev/handbook/introduction)
- [Import Maps Guide](https://github.com/rails/importmap-rails)
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