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

references/deprecation-warnings-reference.md

View on GitHub
# Deprecation Warnings Guide

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

---

## Overview

Deprecation warnings notify you that a specific feature (method, class, or API) will be removed in a future version and should be replaced. Features are deprecated rather than immediately removed to:

- Provide backward compatibility
- Give developers time to update their code
- Allow gradual migration to new patterns

---

## Finding Deprecation Warnings

### Check Existing Deprecation Behavior First

Before reading test logs, sweep for places that already override deprecation behavior. Otherwise "no deprecation warnings in the log" can mean "they're being silenced", and "every test fails" can mean "they've been raising the whole time, unrelated to the upgrade." `config/application.rb` and `config/environments/*.rb` are not the only places this is configured: apps also use the `config.active_support.deprecation =` env DSL, Rails 7.1+ apps use the `deprecators` registry, RSpec autoloads `-r` requires from `.rspec`, and test helpers can install hooks like `RSpec.configure { |c| c.raise_errors_for_deprecations! }`. Minitest apps wire the same behavior from `test/test_helper.rb` and `test/support/`.

```bash
grep -rnE "raise_errors_for_deprecations|(ActiveSupport::Deprecation|Rails\.application\.deprecators|[A-Z]\w*\.deprecator)\.(behavior|disallowed_behavior|silenced)\s*=|(ActiveSupport::Deprecation|Rails\.application\.deprecators|[A-Z]\w*\.deprecator)\.silence\b|config\.active_support\.(deprecation|disallowed_deprecation|disallowed_deprecation_warnings|report_deprecations)\s*=" \
  .rspec spec/.rspec spec/spec_helper.rb spec/rails_helper.rb Rakefile \
  config/ spec/support/ lib/tasks/ \
  test/test_helper.rb test/support/ test/minitest/ 2>/dev/null
```

The trailing `silence\b` alternation catches the block form `ActiveSupport::Deprecation.silence do ... end` (or `{ ... }`), which is the recommended way to scope a silence to a single noisy call site. The `\b` word boundary keeps it from matching `silenced` (which is already covered by the assignment branch).

Which forms appear depends on the app's Rails version:

- `config.active_support.deprecation=` / `ActiveSupport::Deprecation.behavior=` — Rails 3+ (classic global config)
- `.rspec` `-r raise_errors_for_deprecations` / `raise_errors_for_deprecations!` — RSpec hook, any version
- `Rails.application.deprecators` / `<Framework>.deprecator` (e.g. `ActiveRecord.deprecator`) — Rails 7.1+ (deprecators registry)

Running this against a Rails 5–7.0 app and seeing no `deprecators` hits is expected, not a gap.

A common gotcha is a single line in `.rspec`:

```
# .rspec
-r raise_errors_for_deprecations
```

That installs an RSpec hook that raises on every `ActiveSupport::Deprecation.warn`. Easy to miss because nothing about it lives under `config/`.

### In Test Suite Logs

If you have good test coverage, run your test suite and check the logs:

```bash
# Run tests and capture output
bundle exec rspec 2>&1 | tee test_output.log

# Search for deprecation warnings
grep "DEPRECATION WARNING" test_output.log
```

All Rails deprecation warnings start with `DEPRECATION WARNING:`.

### In CI Services

Most CI services (CircleCI, GitHub Actions, Travis CI) display full test output. After the build finishes, search the logs for `DEPRECATION WARNING`.

### In Test Log File

```bash
# After running tests
grep "DEPRECATION WARNING" log/test.log
```

### In Production

The best way to discover production deprecation warnings is through a monitoring tool like [Honeybadger](https://www.honeybadger.io/), [Sentry](https://sentry.io/), or [Airbrake](https://airbrake.io/).

**Configure Rails to notify on deprecations:**

```ruby
# config/environments/production.rb
config.active_support.deprecation = :notify
```

**Subscribe to deprecation events:**

```ruby
# config/initializers/deprecation_warnings.rb

ActiveSupport::Notifications.subscribe('deprecation.rails') do |name, start, finish, id, payload|
  # Honeybadger
  Honeybadger.notify(
    error_class: "DeprecationWarning",
    error_message: payload[:message],
    backtrace: payload[:callstack]
  )

  # Or Sentry
  # Sentry.capture_message(
  #   payload[:message],
  #   level: :warning,
  #   backtrace: payload[:callstack]
  # )

  # Or Airbrake
  # Airbrake.notify(
  #   error_class: "DeprecationWarning",
  #   error_message: payload[:message],
  #   backtrace: payload[:callstack]
  # )
end
```

See the [ActiveSupport Instrumentation Guide](https://guides.rubyonrails.org/active_support_instrumentation.html#subscribing-to-an-event) for more details.

### Alternative: Log to Production Log

```ruby
# config/environments/production.rb
config.active_support.deprecation = :log
```

Then check `log/production.log`, but this can be noisy on high-traffic applications.

---

## Tracking Deprecation Warnings

Once you've collected deprecation warnings, track them systematically:

### 1. Create Issues for Each Root Cause

Use your project management tool (Jira, Linear, GitHub Issues) to create a story for each unique deprecation warning. This helps with:

- Code review organization
- Progress tracking
- Team visibility

### 2. Prioritize by Frequency

Address the most common deprecation warnings first. They often fix the largest number of occurrences with a single change.

### 3. Group Related Warnings

Some warnings share a root cause. For example, `update_attributes` being deprecated affects multiple files but has one fix pattern.

---

## Fixing Deprecation Warnings

### Process

1. **Pick a warning** from the top of your backlog
2. **Understand the fix** - Most warnings clearly state what to replace
3. **Search for all occurrences** in the project
4. **Apply the fix** consistently
5. **Run tests** for affected code
6. **Create a pull request**
7. **Move to the next warning**

### Example Fix

**Warning:**
```
DEPRECATION WARNING: update_attributes is deprecated and will be removed
from Rails 6.1 (please, use update instead)
```

**Search and Replace:**
```bash
# Find all occurrences
grep -r "update_attributes" app/ lib/ --include="*.rb"

# In your editor, replace:
# object.update_attributes(params)
# with:
# object.update(params)
```

### Warnings from Gems

Sometimes deprecation warnings come from gems, not your code. In this case:

1. Check if a newer version of the gem fixes the issue
2. Run `bundle outdated` to see available updates
3. Update the gem: `bundle update gem_name`
4. If no fix exists, consider contributing a patch or finding an alternative

---

## Preventing Future Deprecation Debt

### Treat Warnings as Errors

Configure test and development environments to raise on deprecation:

```ruby
# config/environments/test.rb
config.active_support.deprecation = :raise

# config/environments/development.rb
config.active_support.deprecation = :raise
```

This immediately surfaces deprecations during development and in CI.

### Use Rubocop for Regression Prevention

Write custom Rubocop cops to prevent deprecated patterns. See [Lint/DeprecatedClassMethods](https://github.com/rubocop-hq/rubocop/blob/master/lib/rubocop/cop/lint/deprecated_class_methods.rb) for examples.

Example custom cop:

```ruby
# lib/rubocop/cop/custom/no_update_attributes.rb

module RuboCop
  module Cop
    module Custom
      class NoUpdateAttributes < Base
        MSG = 'Use `update` instead of `update_attributes`.'

        def_node_matcher :update_attributes?, <<~PATTERN
          (send _ {:update_attributes :update_attributes!} ...)
        PATTERN

        def on_send(node)
          return unless update_attributes?(node)
          add_offense(node)
        end
      end
    end
  end
end
```

---

## Rails 6.1+ Disallowed Deprecations

Rails 6.1 introduced a feature to disallow specific deprecations. Once you fix a deprecation, you can prevent it from reappearing:

```ruby
# config/environments/test.rb

# Treat disallowed deprecations as failures
ActiveSupport::Deprecation.disallowed_behavior = [:raise]

# List of disallowed deprecation patterns
ActiveSupport::Deprecation.disallowed_warnings = [
  # String match
  "update_attributes",

  # Symbol match
  :update_attributes,

  # Regex match
  /(update_attributes)!?/,

  # Multiple patterns
  "before_filter",
  "after_filter",
]
```

### How It Works

- **Allowed deprecations**: Logged normally (warning level)
- **Disallowed deprecations**: Raise an exception in development/test, logged as error in production

### Recommended Workflow

1. Fix a deprecation warning
2. Add it to `disallowed_warnings`
3. Any reintroduction will fail tests

---

## Deprecation Configuration Options

| Setting | Behavior |
|---------|----------|
| `:raise` | Raise an exception (stops execution) |
| `:log` | Log to Rails logger |
| `:notify` | Send to `ActiveSupport::Notifications` |
| `:silence` | Ignore (not recommended) |
| `:stderr` | Print to stderr |
| `:report` | Report via error reporter (Rails 7.1+) |

**Recommended settings:**

```ruby
# config/environments/development.rb
config.active_support.deprecation = :raise

# config/environments/test.rb
config.active_support.deprecation = :raise

# config/environments/production.rb
config.active_support.deprecation = :notify
```

---

## Common Deprecation Patterns by Rails Version

### Rails 5.0 → 5.1
- `render :text` → `render :plain`
- `redirect_to :back` → `redirect_back`

### Rails 5.1 → 5.2
- `secrets.yml` → `credentials.yml.enc`
- `config.active_record.belongs_to_required_by_default`

### Rails 5.2 → 6.0
- `update_attributes` → `update`
- Classic autoloader → Zeitwerk

### Rails 6.0 → 6.1
- `Rails.application.secrets` → `Rails.application.credentials`

### Rails 6.1 → 7.0
- `to_s(:format)` → `to_fs(:format)`
- Turbolinks → Turbo

### Rails 7.0 → 7.1
- `before_action` callback order changes
- `config.cache_classes` → `config.enable_reloading`

### Rails 7.1 → 7.2
- `show_exceptions` boolean → symbol
- `params == hash` → `params.to_h == hash`

---

## Quick Reference

### Find Deprecations
```bash
# In test logs
grep "DEPRECATION WARNING" log/test.log

# In CI output
# Search the build log for "DEPRECATION WARNING"

# Run tests with verbose output
RAILS_ENV=test bundle exec rspec 2>&1 | grep "DEPRECATION"
```

### Configure Strict Mode
```ruby
# config/environments/test.rb
config.active_support.deprecation = :raise
```

### Track in Production
```ruby
# config/environments/production.rb
config.active_support.deprecation = :notify

# config/initializers/deprecation_warnings.rb
ActiveSupport::Notifications.subscribe('deprecation.rails') do |*, payload|
  YourErrorTracker.notify(payload[:message])
end
```

---

## Resources

- [Rails Deprecation Behavior](https://guides.rubyonrails.org/configuring.html#config-active-support-deprecation)
- [ActiveSupport Instrumentation](https://guides.rubyonrails.org/active_support_instrumentation.html)
- [Rubocop](https://github.com/rubocop-hq/rubocop)
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