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-5.2-to-6.0.md

View on GitHub
# Rails 5.2 → 6.0 Upgrade Guide

**Ruby Requirement:** 2.5.0+ (2.7+ recommended)

---

## Overview

Rails 6.0 is a major release with significant changes:
- **Zeitwerk** replaces classic autoloader
- **Action Mailbox** for inbound email processing
- **Action Text** for rich text editing
- **Parallel testing** by default
- **Webpacker** as default JavaScript compiler

---

## Breaking Changes

### ðŸ”ī HIGH PRIORITY

#### Zeitwerk Autoloader

**What Changed:**
Rails 6.0 introduces Zeitwerk as the new code autoloader, replacing the classic autoloader.

**Detection Pattern:**
```ruby
require_dependency 'some/file'
```

**Fix:**
Remove all `require_dependency` calls. Zeitwerk auto-loads files based on naming conventions.

```ruby
# BEFORE (Rails 5.2)
require_dependency 'concerns/trackable'

# AFTER (Rails 6.0)
# Just delete the line - Zeitwerk handles loading
```

**Naming Requirements:**
- File `app/models/user_profile.rb` must define `UserProfile`
- File `app/services/payment/processor.rb` must define `Payment::Processor`
- Acronyms: `HTMLParser` → `html_parser.rb`

**Check for issues:**
```bash
rails zeitwerk:check
```

---

`Circular dependency detected` means two files require each other at load time; restructure so one side does not need the other at load, and keep an explicit `require` for the rare edge case only.


#### Ruby 2.5+ Required

**What Changed:**
Rails 6.0 requires Ruby 2.5.0 or newer.

**Fix:**
Upgrade Ruby before Rails:
```bash
# Update .ruby-version
echo "2.7.8" > .ruby-version

# Or use rbenv/rvm
rbenv install 2.7.8
rbenv local 2.7.8
```

---

#### belongs_to Required by Default

**What Changed:**
`belongs_to` associations are required by default (presence validation).

**Detection Pattern:**
```ruby
belongs_to :user  # Now requires user to exist
```

**Fix:**
Add `optional: true` for associations that can be nil:
```ruby
# BEFORE (implicitly optional)
belongs_to :parent_category

# AFTER (explicitly optional)
belongs_to :parent_category, optional: true
```

---

#### protect_from_forgery Default Changed

**What Changed:**
Default CSRF protection strategy changed to `:exception`.

**Detection Pattern:**
```ruby
protect_from_forgery with: :null_session
```

**Fix:**
Review your CSRF strategy. For APIs:
```ruby
# API controllers
class ApiController < ApplicationController
  protect_from_forgery with: :null_session
end
```

---

### ðŸŸĄ MEDIUM PRIORITY

#### update_attributes Deprecated

**What Changed:**
`update_attributes` and `update_attributes!` become deprecated aliases of `update` and `update!`: they still work on 6.0 and emit a deprecation warning on every call. Rails 6.1 removes them, so every call raises `NoMethodError` after the next hop. Replacing them now is the same edit either way.

**Detection Pattern:**
```ruby
user.update_attributes(name: 'New Name')
user.update_attributes!(name: 'New Name')
```

**Fix:**
```ruby
# BEFORE
user.update_attributes(name: 'New Name')

# AFTER
user.update(name: 'New Name')
```

---

#### before_filter Removed

**What Changed:**
`before_filter`, `after_filter`, `skip_before_filter` are removed.

**Fix:**
```ruby
# BEFORE
before_filter :authenticate_user!

# AFTER
before_action :authenticate_user!
```

---

#### render :text Removed

**What Changed:**
`render text: 'content'` is removed.

**Fix:**
```ruby
# BEFORE
render text: 'Hello'

# AFTER
render plain: 'Hello'
```

---

#### render nothing: true Removed

**What Changed:**
`render nothing: true` is removed.

**Fix:**
```ruby
# BEFORE
render nothing: true

# AFTER
head :ok
# or
head :no_content
```

---

#### ActiveStorage Blob API Changes

**What Changed:**
`ActiveStorage::Blob.create_after_upload!` is deprecated.

**Fix:**
```ruby
# BEFORE
ActiveStorage::Blob.create_after_upload!(io: file, filename: 'file.pdf')

# AFTER
ActiveStorage::Blob.create_and_upload!(io: file, filename: 'file.pdf')
```

---

## New Features (Optional)

### Action Mailbox
Process incoming emails:
```ruby
rails action_mailbox:install
```

### Action Text
Rich text editing with Trix:
```ruby
rails action_text:install
```

### Multiple Databases
Configure multiple databases in `database.yml`:
```yaml
production:
  primary:
    database: my_primary_database
  replica:
    database: my_replica_database
    replica: true
```

---

## Migration Steps

### Phase 1: Preparation
```bash
# Create upgrade branch
git checkout -b rails-60-upgrade

# Check current Ruby version
ruby -v

# Upgrade Ruby if needed (to 2.7+)
```

### Phase 2: Gemfile Updates
```ruby
# Gemfile
gem 'rails', '~> 6.0.0'
gem 'webpacker', '~> 5.0'  # New default for JS
```

```bash
bundle update rails
```

### Phase 3: Fix Breaking Changes
1. Remove all `require_dependency` calls
2. Run `rails zeitwerk:check`
3. Fix naming issues
4. Replace `update_attributes` with `update`
5. Add `optional: true` to nullable associations
6. Replace `before_filter` with `before_action`

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

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

### Phase 5: Webpacker (Optional)
If migrating JavaScript:
```bash
rails webpacker:install
```

---

## Zeitwerk Compatibility Checklist

- [ ] No `require_dependency` calls
- [ ] All files follow naming conventions
- [ ] No files with multiple class/module definitions
- [ ] `rails zeitwerk:check` passes
- [ ] No circular dependencies
- [ ] Concerns named correctly

---

## Common Issues — Quick Reference

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

| Error | See |
|-------|-----|
| `Zeitwerk::NameError: expected file ... to define constant ...` | "Zeitwerk Autoloader" — rename the file or the class to match |
| `Circular dependency detected` | "Zeitwerk Autoloader" — restructure, `require` only for real edge cases |
| `uninitialized constant` only in tests | "Zeitwerk Autoloader" — run `bin/rails zeitwerk:check`, check `rails_helper` load order |
| `DEPRECATION WARNING: update_attributes is deprecated and will be removed from Rails 6.1` | "update_attributes Deprecated": replace with `update` before the 6.1 hop |

---

## Gem Compatibility

| Gem | Minimum Version |
|-----|-----------------|
| devise | 4.7.0 |
| cancancan | 3.0.0 |
| pundit | 2.0.0 |
| sidekiq | 6.0.0 |
| rspec-rails | 4.0.0 |
| factory_bot_rails | 5.0.0 |

---

## Resources

- [Rails 6.0 Release Notes](https://guides.rubyonrails.org/6_0_release_notes.html)
- [Zeitwerk Documentation](https://github.com/fxn/zeitwerk)
- [Webpacker Documentation](https://github.com/rails/webpacker)
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