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-4.2-to-5.0.md

View on GitHub
# Rails 4.2 → 5.0 Upgrade Guide

**Ruby Requirement:** 2.2.2+ (2.3+ recommended)

**Based on "The Complete Guide to Upgrade Rails" by FastRuby.io (OmbuLabs)**

---

## Overview

Rails 5.0 is a major release with significant changes:
- **ActionCable** for WebSockets
- **API Mode** for JSON APIs
- **ApplicationRecord** base class
- **belongs_to required by default**
- **Turbolinks 5**
- **Rails command** instead of rake

---

## Breaking Changes

### ðŸ”ī HIGH PRIORITY

#### Ruby 2.2.2+ Required

**Pattern:** `RUBY_VERSION`

**What Changed:**
Rails 5.0 requires Ruby 2.2.2 or newer: the `rails` 5.0 gemspec sets `required_ruby_version >= 2.2.2`, while 4.2 accepts `>= 1.9.3`. Bundler refuses to install 5.0 on an older Ruby, so upgrade Ruby first, while the app is still on Rails 4.2, as its own deploy. Rails 5.0 also has a ceiling the gemspec does not state: the [FastRuby.io compatibility table](https://www.fastruby.io/blog/ruby/rails/versions/compatibility-table.html) lists it as needing Ruby below 2.5, so an app already on Ruby 2.5 or newer has to use Ruby 2.4 for this hop. 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.1.10"

# .ruby-version
2.1.10

# .tool-versions
ruby 2.1.10
```

**Fix:**
```bash
rbenv install 2.3.8
rbenv local 2.3.8
```

**Common Issue:**
If you see `cannot load such file -- test/unit/assertions`, add:
```ruby
# Gemfile
gem 'test-unit'
```

---

#### ApplicationRecord Base Class

**Pattern:** `ACTIVERECORD_BASE`

**What Changed:**
Models now inherit from `ApplicationRecord` instead of `ActiveRecord::Base`.

**Fix:**

1. Create the ApplicationRecord class:
```ruby
# app/models/application_record.rb

class ApplicationRecord < ActiveRecord::Base
  self.abstract_class = true
end
```

2. Update all models:
```ruby
# BEFORE
class User < ActiveRecord::Base
end

# AFTER
class User < ApplicationRecord
end
```

---

#### belongs_to Required by Default

**Pattern:** `BELONGS_TO_REQUIRED`

**What Changed:**
`belongs_to` associations now require the associated record to exist.

**Detection Pattern:**
```ruby
class Post < ApplicationRecord
  belongs_to :author  # Now required!
end
```

**Fix:**

Add `optional: true` for nullable associations:
```ruby
# BEFORE (allowed nil)
belongs_to :parent_category

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

Or disable globally (not recommended):
```ruby
# config/application.rb
config.active_record.belongs_to_required_by_default = false
```

---

#### Strong Parameters Required

**Pattern:** `PROTECTED_ATTRIBUTES`, `ATTR_ACCESSIBLE`

**What Changed:**
`protected_attributes` gem no longer works in Rails 5.

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

# Models
attr_accessible :name, :email
```

**Fix:**
You MUST migrate to Strong Parameters before upgrading:

```ruby
# Remove from Gemfile
# gem 'protected_attributes'

# Remove from models
# attr_accessible :name, :email

# Add to controllers
class UsersController < ApplicationController
  private

  def user_params
    params.require(:user).permit(:name, :email)
  end
end
```

**Tool:** Use [rails_upgrader](https://github.com/fastruby/rails_upgrader) gem to help automate this.

---

#### Parameters No Longer HashWithIndifferentAccess

**Pattern:** `PARAMS_AS_HASH`

**What Changed:**
`params` is now `ActionController::Parameters`, not a hash.

**Detection Pattern:**
```ruby
# These may break
params.slice(:name, :email)
params.except(:id)
params.fetch(:user)
```

**Fix:**
Permit parameters first, then call hash methods:

```ruby
# BEFORE
params[:user].slice(:name, :email)

# AFTER
params.require(:user).permit(:name, :email).to_h.slice(:name, :email)
```

---

### ðŸŸĄ MEDIUM PRIORITY

#### Controller Tests Changed

**Pattern:** `ASSIGNS_IN_TESTS`, `ASSERT_TEMPLATE`

**What Changed:**
`assigns` and `assert_template` are extracted to a gem.

**Detection Pattern:**
```ruby
# In tests
assigns(:user)
assert_template 'index'
```

**Fix:**
```ruby
# Gemfile
gem 'rails-controller-testing', group: :test
```

---

#### File Upload Testing Changed

**Pattern:** `UPLOAD_FILE_TEST`

**What Changed:**
Use `Rack::Test::UploadedFile` instead of `ActionDispatch::Http::UploadedFile`.

**Fix:**
```ruby
# BEFORE
ActionDispatch::Http::UploadedFile.new(...)

# AFTER
Rack::Test::UploadedFile.new(file_path, 'image/png')
```

---

#### Callback Halting Changed

**Pattern:** `CALLBACK_HALT`

**What Changed:**
Returning `false` from a before_* Active Record or Active Model callback no longer halts the
chain. On 5.0 it still halts, with a deprecation warning, while
`ActiveSupport.halt_callback_chains_on_return_false` is `true` (the setting an upgraded app gets);
new 5.0 apps set it to `false`. From 5.1 the setting is ignored (it only warns, and 5.2 removes
it), so an app still on `true` starts saving or destroying at the 5.1 hop, warned only that the
setting is deprecated.
Nothing raises. A `before_save` that returns `false` saves the record on Active Record 5.1 and
later and refuses it on 4.2, for the method form and the block form alike.

**Detection Pattern:**
Three shapes yield the halting `false`, and the bare trailing one is the easiest to miss:

```ruby
before_save :check_something
before_destroy :guard
before_save { false if archived? }

def check_something
  return false if invalid_condition
end

def guard
  if protected?
    false            # the method's value; halts on 4.2, ignored from 5.1
  else
    true
  end
end
```

A callback whose last expression only evaluates to `false` (`!locked?`) halts too, and no grep
finds it, so read the last line of each before_* callback.

Controller filters are not affected: `before_action` never halted on `false`. Its terminator was
`response_body` through 4.2 and is `performed?` from 5.0, so only `render` or `redirect_to` has
ever stopped the action.

**Fix:**
```ruby
# BEFORE
def check_something
  return false if invalid_condition
end

# AFTER
def check_something
  throw :abort if invalid_condition
end
```

`throw :abort` raises `UncaughtThrowError: uncaught throw :abort` on 4.2, so a dual-boot app
branches it:

```ruby
def check_something
  return unless invalid_condition
  NextRails.next? ? throw(:abort) : false
end
```

---

#### Rails Command Replaces Rake

**Pattern:** `RAKE_COMMANDS`

**What Changed:**
Use `rails` instead of `rake` for many commands.

**Old vs New:**
```bash
# BEFORE
rake db:migrate
rake test
rake routes

# AFTER (both work, but rails is preferred)
rails db:migrate
rails test
rails routes
```

---

#### `redirect_to :back` Deprecated

**Pattern:** `REDIRECT_TO_BACK_DEPRECATED`

**What Changed:**
`redirect_to :back` is deprecated in Rails 5.0. It still works and emits a deprecation warning, but it is **removed outright in Rails 5.1** — fix all call sites now to avoid a runtime break on the next hop.

**Detection Pattern:**
```ruby
redirect_to :back
redirect_to :back, notice: 'Done!'
```

**Fix:**
```ruby
# BEFORE
redirect_to :back

# AFTER
redirect_back(fallback_location: root_path)
redirect_back(fallback_location: root_path, notice: 'Done!')
```

`redirect_back` accepts a `fallback_location:` used when `HTTP_REFERER` is missing — without it, requests with no referer raise `ActionController::RedirectBackError`.

---

## Gem Compatibility

Check gems at [RailsBump](https://railsbump.org/) before upgrading.

Common gems that need updating:

| Gem | Rails 4.2 | Rails 5.0 |
|-----|-----------|-----------|
| devise | 3.5+ | 4.2+ |
| cancancan | 1.15+ | 2.0+ |
| ransack | 1.7+ | 1.8+ |
| activeadmin | 1.0+ | 1.1+ |

---

## Migration Steps

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

# Ensure Ruby 2.2.2+
ruby -v

# Check gem compatibility
# Visit railsbump.org
```

### Phase 2: Pre-requisites
1. **Migrate to Strong Parameters** (if using protected_attributes)
2. **Update callbacks** that return false
3. **Check gem compatibility**

### Phase 3: Gemfile Updates
```ruby
# Gemfile
gem 'rails', '~> 5.0.0'

# Add for testing
gem 'rails-controller-testing', group: :test
```

```bash
bundle update rails
```

### Phase 4: Create ApplicationRecord
```ruby
# app/models/application_record.rb
class ApplicationRecord < ActiveRecord::Base
  self.abstract_class = true
end
```

Update all models to inherit from `ApplicationRecord`.

### Phase 5: Fix belongs_to
Add `optional: true` to associations that can be nil.

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

### Phase 7: Testing
- Run full test suite
- Test all forms and validations
- Test model associations
- Test callbacks

---

## belongs_to Migration Checklist

For each model with `belongs_to`:

- [ ] Check if association can be nil
- [ ] Add `optional: true` if nullable
- [ ] Test create/update without the association
- [ ] Verify validation messages

---

## Common Issues — Quick Reference

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

| Error | See |
|-------|-----|
| `Author must exist` validation failure | "belongs_to Required by Default" — `optional: true` where the association is optional |
| `ActiveModel::ForbiddenAttributesError` | "Strong Parameters Required" — pass permitted params |
| Callback returning `false` no longer stops the save | "Callback Halting Changed" — `throw :abort` |

---

## New Features to Explore

After upgrading, consider using:

- **ActionCable** for real-time features
- **API Mode** for JSON-only APIs
- **ActiveRecord::Attributes** for custom types
- **ApplicationRecord** for shared model logic

---

## Resources

- [Rails 5.0 Release Notes](https://guides.rubyonrails.org/5_0_release_notes.html)
- [RailsDiff 4.2 to 5.0](http://railsdiff.org/4.2.10/5.0.7)
- [Strong Parameters Guide](https://guides.rubyonrails.org/action_controller_overview.html#strong-parameters)
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