ombulabs/claude-code_rails-upgrade-skill / rails-upgrade
rails-upgrade
VerifiedAnalyzes 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.
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)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 119k | Updated | Claude CodeCodex | Verified | Install |
| 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: 118k | Updated | Claude CodeCodex | Verified | Install |
| 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: 108k | Updated | Claude CodeCodex | Verified | Install |
| 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: 108k | Updated | Claude CodeCodex | Verified | Install |