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.
detection-scripts/patterns/rails-70-patterns.yml
View on GitHubversion: "7.0"
description: "Breaking change patterns for Rails 6.1 → 7.0 upgrade"
upgrade_findings:
high_priority:
- name: "Ruby version requirement"
kind: "breaking"
pattern: "^\\s*(?:ruby\\s*\\(?\\s*[\"'](?:=\\s*|~>\\s*(?=\\d+\\.\\d+\\.\\d))?|ruby-|ruby\\s+)?(?:1\\.\\d+|2\\.[0-6])(?:\\.\\d+)*(?![\\d.])|^\\s*ruby\\s*\\(?\\s*[\"']~>\\s*1\\.\\d+(?![\\d.])"
exclude: ""
search_paths:
- "Gemfile"
- ".ruby-version"
- ".tool-versions"
explanation: "Rails 7.0 requires Ruby 2.7.0 or newer. Flags a Ruby below 2.7.0 in .ruby-version or .tool-versions, and a Gemfile `ruby` line that rules it out (an exact version, or a `~>` whose upper bound is below 2.7.0); a requirement that still allows 2.7.0, such as `>=`, is not flagged"
fix: "Upgrade Ruby to 2.7.0+ (3.0+ recommended)"
variable_name: "RUBY_VERSION"
- name: "Explicit format/handler extension in template: or layout:"
kind: "breaking"
pattern: "(template|layout):\\s*[\"'][^\"']*\\.(html|erb)\\b"
exclude: ""
search_paths:
- "app/controllers/"
- "app/mailers/"
- "app/views/"
- "app/helpers/"
explanation: "A call like `render template: \"posts/show.html.erb\"` or `layout: \"pdf.html\"` worked on 6.1 and raises ActionView::MissingTemplate on 7.0. 6.1 tolerated it and warned: action_view/template/resolver.rb#find_template_paths_from_details emitted \"Rendering actions with '.' in the name is deprecated\" whenever the name contained a dot. That code path is gone in 7.0, so the dotted name is taken literally and matches no template. Most commonly hit via wicked_pdf's `render pdf:` helper, which forwards :template/:layout straight through. A related, non-regex-detectable failure mode: if the render call runs inside a non-html respond_to format block (e.g. `format.pdf do render pdf: ... end`) and does not pass an explicit `formats:` option, Rails resolves the template using the block's format (:pdf) instead of :html, and raises MissingTemplate even with a bare template name -- 6.1 fell back to :html here, 7.0 does not. See workflows/07-boot-smoke-test-workflow.md notes: neither this pattern nor the boot smoke test catches the formats: variant because it only manifests when the specific action+format combination is actually invoked, not at boot."
fix: "Drop the format/handler extension from the string: template: \"posts/show.html.erb\" -> template: \"posts/show\"; layout: \"pdf.html\" -> layout: \"pdf\". If the render happens inside a non-html format.<x> block, also add formats: [:html] explicitly so template resolution doesn't use the block's format."
variable_name: "EXPLICIT_TEMPLATE_EXTENSION"
- name: "Webpacker usage"
kind: "migration"
pattern: "webpacker|javascript_pack_tag"
exclude: "importmap"
search_paths:
- "Gemfile"
- "config/"
- "app/views/"
explanation: "Rails 7.0 replaces Webpacker with Import Maps or jsbundling-rails"
fix: "Migrate to Import Maps, esbuild, or rollup. Remove Webpacker."
variable_name: "WEBPACKER"
- name: "form_with local option"
kind: "migration"
pattern: "form_with.*local:\\s*(true|false)"
exclude: ""
search_paths:
- "app/views/"
explanation: "Rails 7.0 changes form_with to submit remotely by default with Turbo"
fix: "Remove local: true (now default is remote with Turbo). Add data: { turbo: false } if needed."
variable_name: "FORM_WITH_LOCAL"
medium_priority:
- name: "secrets.yml usage"
kind: "migration"
pattern: "Rails\\.application\\.secrets"
exclude: "credentials"
search_paths:
- "app/"
- "lib/"
- "config/"
explanation: "Rails.application.secrets still works at 7.0 with no deprecation warning; def secrets in railties/lib/rails/application.rb is byte-for-byte identical to 6.1. The runtime API is officially deprecated in 7.1, so migrating to Rails.application.credentials at this hop avoids rework on the next one"
fix: "Move values from config/secrets.yml into config/credentials.yml.enc (`rails credentials:edit`), then update readers: Rails.application.secrets.api_key → Rails.application.credentials.api_key. config/master.key must NOT be committed"
variable_name: "SECRETS_YML"
- name: "ActiveRecord enum prefix/suffix"
kind: "migration"
pattern: "enum.*:.*\\{"
exclude: ""
search_paths:
- "app/models/"
explanation: "Rails 7.0 changes enum syntax - hash syntax preferred"
fix: "Review enums. New syntax: enum status: { draft: 0, published: 1 }"
variable_name: "ENUM_SYNTAX"
- name: "image_tag skip_pipeline"
kind: "optional"
pattern: "image_tag.*skip_pipeline"
exclude: ""
search_paths:
- "app/views/"
- "app/helpers/"
explanation: "skip_pipeline is fully supported at Rails 7.0; image_tag's implementation is byte-for-byte identical to 6.1. The option was actually expanded at 7.0 to also work on stylesheet_link_tag. This entry flags call sites for review when migrating away from Sprockets to Propshaft / Importmap, but the option itself does not change at this hop and existing calls continue to work"
fix: "No change required at the 7.0 hop. If you are also migrating off the Sprockets asset pipeline, audit each skip_pipeline call to confirm it is still doing what you intend under the new pipeline; otherwise leave as-is"
variable_name: "IMAGE_TAG_PIPELINE"
- name: "ActiveStorage variant syntax"
kind: "migration"
pattern: "\\.variant\\(.*resize:"
exclude: ""
search_paths:
- "app/"
explanation: "load_defaults 7.0 sets config.active_storage.variant_processor = :vips (railties configuration.rb); below that the processor stays :mini_magick and resize: keeps working with no warning. Under vips, resize: is not an image_processing macro, so it is forwarded to libvips, which does not take an ImageMagick geometry string like \"100x100>\". A named variant declared without parentheses (a.variant :thumb, resize: ...) is missed"
fix: "Rewrite with the image_processing macros, which work on both processors and both Rails versions: variant(resize_to_limit: [100, 100]), variant(resize_to_fill: [100, 100]). Or keep ImageMagick after load_defaults 7.0 with config.active_storage.variant_processor = :mini_magick"
variable_name: "ACTIVE_STORAGE_VARIANT"
- name: "Turbolinks"
kind: "migration"
pattern: "turbolinks|Turbolinks"
exclude: ""
search_paths:
- "Gemfile"
- "app/javascript/"
- "app/assets/"
explanation: "Turbolinks replaced by Turbo in Rails 7.0"
fix: "Replace turbolinks with @hotwired/turbo. Update event listeners."
variable_name: "TURBOLINKS"
- name: "UJS (rails-ujs)"
kind: "migration"
pattern: "rails-ujs|@rails/ujs"
exclude: ""
search_paths:
- "Gemfile"
- "app/javascript/"
- "package.json"
explanation: "Rails UJS is replaced by Turbo and Stimulus in Rails 7.0"
fix: "Remove rails-ujs. Use Turbo for remote forms and Stimulus for JavaScript."
variable_name: "RAILS_UJS"
- name: "redirect_to open redirect protection"
kind: "breaking"
pattern: "redirect_(to|back_or_to)\\s+(params\\[|session\\[|request\\.refer|[\"'][^\"']*(https?://|#\\{))"
exclude: "allow_other_host"
search_paths:
- "app/controllers/"
- "app/"
- "lib/"
explanation: "load_defaults 7.0 sets config.action_controller.raise_on_open_redirects = true. With it on, redirect_to and redirect_back_or_to to a host different from the current one raise ActionController::Redirecting::UnsafeRedirectError instead of redirecting. This is not a deprecation and there is no warning phase; it is gated by load_defaults 7.0, so apps only see it once they bump load_defaults to 7.0 (which is why it often surfaces during a later hop). Redirects to dynamic or external destinations (params, session, request.referer, or a literal/interpolated URL) are the ones that break; redirects to path helpers and model records are unaffected"
fix: "For each intentional external redirect, pass allow_other_host: true, e.g. redirect_to \"https://example.com\", allow_other_host: true. Never pass allow_other_host: true on a destination built from untrusted input (params, session, request.referer) without validating it against an allowlist first, or the open-redirect protection is defeated. If a redirect target is internal, rewrite it as a path/url helper so it passes without the flag"
variable_name: "OPEN_REDIRECT_PROTECTION"
- name: "to_s(:format) deprecation"
kind: "deprecation"
pattern: "\\.to_s\\(:"
exclude: ""
search_paths:
- "app/"
- "lib/"
explanation: "to_s(:format) is deprecated in favor of to_fs(:format)"
fix: "Replace to_s(:format) with to_fs(:format)"
variable_name: "TO_S_FORMAT"
low_priority:
- name: "Spring usage"
kind: "optional"
pattern: "gem ['\"]spring['\"]"
exclude: "\\A\\s*#"
search_paths:
- "Gemfile"
explanation: "Rails 7.0 no longer adds spring to new apps (the Gemfile template only has it commented out). An app that keeps it needs spring 4.0 or later: 4.0.0 is the first release whose README lists Rails 7.0, and spring 3.x README stops at 6.0"
fix: "Remove spring and bin/spring if the team does not rely on it, or bump to gem \"spring\", \">= 4.0\" (needs Rails 6.0 or later, so it runs on both sides of the dual boot)"
variable_name: "SPRING"
- name: "config.action_controller.urlsafe_csrf_tokens set explicitly"
kind: "deprecation"
pattern: "\\burlsafe_csrf_tokens\\s*="
exclude: "\\A\\s*#"
search_paths:
- "config/"
explanation: "Rails 7.0 makes URL-safe CSRF tokens the only default (actionpack 7.0 sets urlsafe_csrf_tokens = true) and deprecates the setting: assigning it warns \"URL-safe CSRF tokens are now the default. Use 6.1 defaults or above.\" for true and \"Non-URL-safe CSRF tokens are deprecated. Use 6.1 defaults or above.\" for false. Rails 7.1 removes the setting. An app on load_defaults below 6.1 gets the second warning with no line of its own, because load_defaults 5.0 sets it to false; this pattern only finds an explicit assignment. Tokens keep working across a rolling deploy: 7.0 still decodes the standard base64 tokens 6.1 issued"
fix: "Delete the line on the Rails 7.0 side: `config.action_controller.urlsafe_csrf_tokens = true unless NextRails.next?` keeps it for the 6.1 side only. If the app is on load_defaults below 6.1, move to 6.1 defaults or above, which stops setting it to false"
variable_name: "URLSAFE_CSRF_TOKENS"
dependencies:
importmap:
check: true
gem_name: "importmap-rails"
message: "Rails 7.0 uses Import Maps by default for JavaScript"
url: "https://github.com/rails/importmap-rails"
turbo:
check: true
gem_name: "turbo-rails"
message: "Rails 7.0 uses Turbo (Hotwire) for SPA-like navigation"
url: "https://github.com/hotwired/turbo-rails"
stimulus:
check: true
gem_name: "stimulus-rails"
message: "Rails 7.0 uses Stimulus for JavaScript behaviors"
url: "https://github.com/hotwired/stimulus-rails"
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 |