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

detection-scripts/patterns/rails-51-patterns.yml

View on GitHub
version: "5.1"
description: "Breaking change patterns for Rails 5.0 → 5.1 upgrade"

upgrade_findings:
  high_priority:
    - name: "render :text removed"
      kind: "breaking"
      pattern: "\\brender\\s+(:text\\s*=>|text:)"
      exclude: ""
      search_paths:
        - "app/controllers/"
      explanation: "Rails 5.1 removes `render text: ...`. Calls raise ArgumentError at runtime"
      fix: "Use `render plain: 'content'` for text/plain, or `render html: '<p>..'.html_safe` for explicit HTML"
      variable_name: "RENDER_TEXT"

    - name: "render :nothing removed"
      kind: "breaking"
      pattern: "\\brender\\s+(:nothing\\s*=>|nothing:)"
      exclude: ""
      search_paths:
        - "app/controllers/"
      explanation: "Rails 5.1 removes `render nothing: true`. Calls raise ArgumentError at runtime"
      fix: "Replace with `head :ok` (200 + empty body) or `head :no_content` (204)"
      variable_name: "RENDER_NOTHING"

    - name: "redirect_to :back removed"
      kind: "breaking"
      pattern: "redirect_to\\s+:back\\b"
      exclude: ""
      search_paths:
        - "app/controllers/"
      explanation: "Rails 5.1 removes `redirect_to :back` outright (it was deprecated in 5.0). Callers raise at runtime"
      fix: "Replace with `redirect_back(fallback_location: root_path)` and pass any flash/notice options as keyword arguments"
      variable_name: "REDIRECT_TO_BACK"

    - name: "*_filter callback methods removed"
      kind: "breaking"
      pattern: "\\b(before|after|around|skip|skip_before|skip_after|skip_around|prepend_before|prepend_after|prepend_around|append_before|append_after|append_around)_filter\\b"
      exclude: ""
      search_paths:
        - "app/controllers/"
        - "app/mailers/"
        - "lib/"
      explanation: "Rails 5.1 removes every `*_filter` callback method from AbstractController::Callbacks (deprecated in 5.0, no warning in 4.2), including the bare `skip_filter`. Controllers and mailers both include that module, so a class that calls one raises NoMethodError when it loads. Use the `*_action` variants"
      fix: "Rename: before_filter to before_action, skip_before_filter to skip_before_action, and so on; behavior is identical and the *_action names exist in 5.0. Replace skip_filter with the skip_before_action / skip_after_action / skip_around_action that matches the callback"
      variable_name: "FILTER_METHODS"

    - name: "ActiveRecord::Relation#uniq removed"
      kind: "breaking"
      pattern: "\\.uniq(\\b|\\()"
      exclude: "\\.(to_a|map|pluck|select|reject|each|values|keys|compact)[^\\n]*\\.uniq"
      search_paths:
        - "app/models/"
        - "app/controllers/"
      explanation: "Rails 5.1 removes the deprecated uniq / uniq! aliases of distinct / distinct! on relations and model classes. Model.uniq and relation.uniq! raise NoMethodError; relation.uniq now goes to the loaded records, so it runs the query without DISTINCT, loads every row and returns an Array, and a query method chained after it raises NoMethodError. uniq on an association (post.comments.uniq) behaves as before. The pattern also matches Array#uniq: the exclude skips common array chains, so check each receiver"
      fix: "Replace .uniq / .uniq! on Active Record relations and model classes with .distinct / .distinct!, which exist in 5.0. Leave Array#uniq as it is"
      variable_name: "RELATION_UNIQ"

    - name: "use_transactional_fixtures removed"
      kind: "breaking"
      pattern: "use_transactional_fixtures"
      exclude: "\\bconfig\\.use_transactional_fixtures\\b"
      search_paths:
        - "test/"
        - "spec/"
      explanation: "Rails 5.1 removes the `use_transactional_fixtures` class attribute from ActiveRecord::TestFixtures (renamed to `use_transactional_tests` and deprecated in Rails 5.0). Calling the setter raises NoMethodError when test_helper.rb loads. RSpec's `config.use_transactional_fixtures` in spec/rails_helper.rb is an rspec-rails setting that still works, so the exclude skips it"
      fix: "Rename the setting to `self.use_transactional_tests = true` in your test base class / test_helper.rb"
      variable_name: "USE_TRANSACTIONAL_FIXTURES"

    - name: "Controller test positional arguments"
      kind: "breaking"
      pattern: "^\\s*(get|post|put|patch|delete|head)\\s+[:'\"][^,\\n]+,\\s*(\\{|[a-z_]+:)"
      exclude: "params:|session:|flash:|headers:|body:|xhr:|format:"
      search_paths:
        - "test/controllers/"
        - "test/functional/"
        - "spec/controllers/"
        - "spec/requests/"
      explanation: "Rails 5.1 drops support for positional arguments in controller test helpers. All parameters must be keyword-argument form"
      fix: "Wrap params/session/flash in keyword args: `get :show, params: { id: 1 }, session: { user_id: 1 }, flash: { notice: 'hi' }`"
      variable_name: "CONTROLLER_TEST_POSITIONAL"

    - name: "halt_callback_chains_on_return_false"
      kind: "deprecation"
      pattern: "halt_callback_chains_on_return_false"
      exclude: ""
      search_paths:
        - "config/"
      explanation: "Rails 5.1 removes the `return false` halt: a before_* callback on an Active Record or Active Model object that returns false no longer stops the chain, and nothing warns. In Rails 5.0 it still halted, with a deprecation warning, while ActiveSupport.halt_callback_chains_on_return_false was true (the default; `rails app:update` wrote it as true). The 5.1 setter only logs a deprecation warning and changes nothing; Rails 5.2 removes it (see rails-52-patterns.yml HALT_CALLBACK_CHAINS_ON_RETURN_FALSE). A line set to true means the app may still rely on `return false`; an app with no line had the same default"
      fix: "Before the bump, run the test suite on Rails 5.0 and replace every callback behind the deprecation warning `will not implicitly halt a callback chain in Rails 5.1` with `throw :abort`, then remove the assignment. throw :abort works on 5.0 too"
      variable_name: "HALT_CALLBACK_CHAINS_DEPRECATION"

  medium_priority:
    - name: "raise_in_transactional_callbacks config (dead setting)"
      kind: "breaking"
      pattern: "raise_in_transactional_callbacks"
      exclude: ""
      search_paths:
        - "config/"
      explanation: "Rails 5.1 removes the raise_in_transactional_callbacks config option. The 5.0+ behavior (always raise) is now the only behavior"
      fix: "Remove `config.active_record.raise_in_transactional_callbacks = true` from config/application.rb or environment configs"
      variable_name: "RAISE_IN_TRANSACTIONAL_CALLBACKS"

    - name: "serve_static_files config renamed"
      kind: "breaking"
      pattern: "config\\.serve_static_files"
      exclude: ""
      search_paths:
        - "config/"
      explanation: "Rails 5.1 renames `config.serve_static_files` to `config.public_file_server.enabled`"
      fix: "Rename: `config.public_file_server.enabled = <value>` (or `= ENV['RAILS_SERVE_STATIC_FILES'].present?` for the production default)"
      variable_name: "SERVE_STATIC_FILES_RENAME"

    - name: "static_cache_control config renamed"
      kind: "breaking"
      pattern: "config\\.static_cache_control"
      exclude: ""
      search_paths:
        - "config/"
      explanation: "Rails 5.1 renames `config.static_cache_control` to `config.public_file_server.headers` (and the value is now a hash, not a string)"
      fix: "Rename and restructure: `config.public_file_server.headers = { 'Cache-Control' => 'public, max-age=3600' }`"
      variable_name: "STATIC_CACHE_CONTROL_RENAME"

    - name: "application.secrets nested string-key access"
      kind: "breaking"
      pattern: "Rails\\.application\\.secrets\\[[^\\]]+\\]\\[['\"]"
      exclude: ""
      search_paths:
        - "app/"
        - "config/"
        - "lib/"
      explanation: "Rails 5.1 loads secrets.yml with all keys (including nested) as symbols. Nested string-key access silently returns nil"
      fix: "Use symbol keys throughout: `Rails.application.secrets[:smtp_settings][:address]` instead of `[\"address\"]`"
      variable_name: "SECRETS_STRING_KEYS"

    - name: "application.secrets method-accessor string-key access"
      kind: "breaking"
      pattern: "Rails\\.application\\.secrets\\.\\w+\\[['\"]"
      exclude: ""
      search_paths:
        - "app/"
        - "config/"
        - "lib/"
      explanation: "Rails 5.1 loads secrets.yml with all keys as symbols. Method-accessor style followed by string-key lookup silently returns nil"
      fix: "Use symbol keys: `Rails.application.secrets.smtp_settings[:address]` instead of `[\"address\"]`"
      variable_name: "SECRETS_METHOD_ACCESSOR_STRING_KEYS"

    - name: "ActionDispatch::ParamsParser::ParseError"
      kind: "deprecation"
      pattern: "ActionDispatch::ParamsParser::ParseError"
      exclude: ""
      search_paths:
        - "app/controllers/"
        - "app/middleware/"
        - "lib/"
      explanation: "Rails 5.1 deprecates ActionDispatch::ParamsParser::ParseError in favor of ActionDispatch::Http::Parameters::ParseError. The old constant is preserved at 5.1 with a deprecation warning when referenced; removal scheduled for a later Rails version. Apps usually hit this in rescue handlers around malformed JSON / params"
      fix: "Replace ActionDispatch::ParamsParser::ParseError with ActionDispatch::Http::Parameters::ParseError in rescue clauses"
      variable_name: "PARAMS_PARSER_ERROR"

    - name: "set_callback / skip_callback string :if / :unless"
      kind: "deprecation"
      pattern: "(set_callback|skip_callback)\\b[^\\n]*(?:\\b(?:if|unless):|:(?:if|unless)\\s*=>)\\s*['\"]"
      exclude: ""
      search_paths:
        - "app/"
        - "lib/"
      explanation: "Rails 5.1 deprecates passing a string to :if / :unless options on set_callback and skip_callback. Use a symbol (method name) or a lambda. NOISY REGEX: matches set_callback / skip_callback call sites with inline string conditions; most projects do not call these directly (they use the higher-level before_*, after_* DSL covered by FILTER_STRING_CONDITIONS in this file). For projects that do call them, inspect each match"
      fix: "Replace the string with a symbol: `set_callback :save, :before, :method_name, if: :should_run?` instead of `if: 'should_run?'`. For inline expressions use a lambda: `if: -> { ... }`"
      variable_name: "SET_CALLBACK_STRING_CONDITIONS"

    - name: "String conditions in controller filters"
      kind: "deprecation"
      pattern: "(before|after|around|skip_before|skip_after|skip_around|prepend_before|prepend_after|prepend_around|append_before|append_after|append_around)_(action|filter)\\b[^\\n]*(?:\\b(?:if|unless):|:(?:if|unless)\\s*=>)\\s*['\"]"
      exclude: ""
      search_paths:
        - "app/controllers/"
      explanation: "Rails 5.1 deprecates a string `if:` / `unless:` condition on controller filters: before_action and the rest call set_callback, which logs a deprecation warning and still evaluates the string. Rails 5.2 raises ArgumentError. The warning fires only when the option is a single string, not when only: / except: is also given (Rails wraps the conditions in an array), so trust the pattern over the logs"
      fix: "Replace the string with a symbol: `if: :has_project_guest_id` instead of `if: 'has_project_guest_id'`. For inline expressions, use a lambda: `if: -> { ... }`"
      variable_name: "FILTER_STRING_CONDITIONS"

  low_priority:
    - name: "lock! on dirty AR record"
      kind: "deprecation"
      pattern: "\\.lock!(?=\\(|\\s|$)"
      exclude: ""
      search_paths:
        - "app/"
        - "lib/"
      explanation: "Rails 5.1 deprecates calling #lock! on an ActiveRecord record with unsaved changes. activerecord/lib/active_record/locking/pessimistic.rb at 5.1 emits ActiveSupport::Deprecation.warn 'Locking a record with unpersisted changes is deprecated and will raise an exception in Rails 5.2'. NOISY REGEX: matches every .lock! call site; most are correct usage on persisted records with no in-memory edits. Audit each match. The 5.2 hop turns this into a RuntimeError (see rails-52-patterns.yml LOCK_BANG_UNPERSISTED)"
      fix: "Save (or reload) before locking: record.save; record.lock!. If you intended to lock and then mutate, the correct order is record.lock! followed by the assignment + save"
      variable_name: "LOCK_BANG_DEPRECATION"

    - name: "raise_on_unfiltered_parameters config"
      kind: "deprecation"
      pattern: "raise_on_unfiltered_parameters"
      exclude: ""
      search_paths:
        - "config/"
      explanation: "Rails 5.1 deprecates config.action_controller.raise_on_unfiltered_parameters and ignores it: ActionController::Parameters#to_h and #to_hash always raise ActionController::UnfilteredParameters on unpermitted params. Setting it to true logs a deprecation warning at boot; setting it to false does nothing, so an app that ran with false (the Rails 5.0 default when the line is absent) starts raising where it calls to_h on unpermitted params"
      fix: "Remove the line from config/application.rb, config/initializers/new_framework_defaults.rb or environment configs. If it was false, call permit(...) before to_h, or to_unsafe_h where the unfiltered hash is intended"
      variable_name: "RAISE_ON_UNFILTERED_PARAMS"

    - name: "Defining quoted_id"
      kind: "deprecation"
      pattern: "def\\s+quoted_id\\b"
      exclude: ""
      search_paths:
        - "app/models/"
        - "lib/"
      explanation: "Rails 5.1 deprecates #quoted_id. connection.quote still calls a quoted_id defined on a non-Active Record object (a value object bound into a string condition such as where('total_cents = ?', money)), with the warning `Defining #quoted_id is deprecated and will be ignored in Rails 5.2`. An Active Record record is now quoted by its primary key before that check, so a quoted_id override on a model is no longer called at all, with no warning. Rails 5.2 ignores quoted_id everywhere (see rails-52-patterns.yml QUOTED_ID_METHOD)"
      fix: "Migrate the logic to a custom ActiveModel::Type (define #serialize / #cast) or accept the model's default quoting behavior"
      variable_name: "QUOTED_ID_DEPRECATION"

    - name: "HashWithIndifferentAccess.new_from_hash_copying_default removed"
      kind: "breaking"
      pattern: "\\bnew_from_hash_copying_default\\b"
      exclude: ""
      search_paths:
        - "app/"
        - "config/"
        - "lib/"
      explanation: "Rails 5.1 removes ActiveSupport::HashWithIndifferentAccess.new_from_hash_copying_default, deprecated in 5.0 where it already behaved like .new. Calling it raises NoMethodError"
      fix: "Call ActiveSupport::HashWithIndifferentAccess.new(hash) instead, which copies the default the same way on 5.0"
      variable_name: "HWIA_NEW_FROM_HASH_COPYING_DEFAULT"

dependencies:
  webpacker:
    check: false
    gem_name: "webpacker"
    message: "New Rails 5.1 default for JavaScript bundling via Webpack + Yarn. Optional — adopt only if moving off Sprockets for JS"
    url: "https://github.com/rails/webpacker"

  rails-controller-testing:
    check: true
    gem_name: "rails-controller-testing"
    message: "Still required if tests use assigns() or assert_template (carried over from the 5.0 extraction)"
    url: "https://github.com/rails/rails-controller-testing"
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