rails-upgrade-skill

🥈Silver

Automates the upgrade of Rails applications from version 7.0 to 8.1. Benefits developers and operations teams by reducing manual effort and minimizing downtime. Integrates with existing Rails projects and CI/CD pipelines.

7940Updated 2mo ago

Intermediate30min to implementautomation

Saves ~60 min per use

Quick InstallView Source

git clone https://github.com/maquina-app/rails-upgrade-skill.git

Works with:

Claude

Overview

About This Skill

Rails Upgrade Assistant analyzes your Rails application to identify breaking changes, deprecations, and migration requirements when upgrading from version 7.0 through 8.1.1. The skill generates a detection script that scans your codebase in under 30 seconds, pinpointing specific files and line numbers affected by the upgrade. After you run the detection script and share the findings, it produces comprehensive upgrade reports with before/after code examples, step-by-step migration plans, testing checklists, and rollback procedures. This workflow saves 2–3 hours per upgrade and delivers 90%+ accuracy by analyzing your actual codebase rather than providing generic guidance. Rails development teams benefit from clear, actionable migration paths with file-specific references ready for editor integration.

How to Use

["1. **Prepare Your Project:** Ensure your Rails 7.0 app has a clean git history with no uncommitted changes. Run `bundle exec rails about` to confirm the current version.","2. **Run the Skill:** Paste the prompt template into your AI assistant, replacing [PLACEHOLDERS] with your project paths (e.g., `/path/to/your/app`, `Gemfile`, `config/`, `log/upgrade.log`, `staging`).","3. **Review the Output:** The AI will generate a structured upgrade plan with dependency updates, configuration changes, and a rollout strategy. Verify the commands match your project structure.","4. **Execute in Staging First:** Follow the rollout strategy exactly, starting with the staging environment. Use `git diff` to review changes before committing.","5. **Monitor and Iterate:** After deploying to production, monitor logs (`tail -f log/production.log`) and performance metrics. Report any issues to the AI for adjustments to the rollback plan.","Tip: Use `rails app:update` to generate Rails 8.1-specific files, then compare them with your existing config using `git diff`. This helps identify manual changes needed."]

Use Cases

Upgrade Rails application from 7.0 to 7.1 with breaking change detection

Plan multi-hop upgrades (e.g., 7.0 → 7.1 → 7.2 → 8.0 → 8.1) sequentially

Identify deprecations and required code changes before running rails app:update

Generate codebase-specific migration reports with file:line references

Setup & Installation

Quick Install

No install command available. Check the GitHub repository for manual installation instructions.

Alternative Install (Git Clone)

git clone https://github.com/maquina-app/rails-upgrade-skill

Requirements

Claude Code or compatible AI agent
Works with: Claude

Quick Start Guide

Install the Skill

Copy the install command above and run it in your terminal.

Open Your AI Agent

Launch Claude Code, Cursor, or your preferred AI coding agent.

Try It Out

Use the prompt template or examples below to test the skill.

Customize

Adapt the skill to your specific use case and workflow.

Usage Examples

Prompt Template

Upgrade the Rails application in [PROJECT_PATH] from Rails 7.0 to Rails 8.1. Follow the official Rails upgrade guide and generate a migration plan that includes: 1) Required dependency updates in [GEMFILE_PATH], 2) Configuration changes needed in [CONFIG_PATH], 3) Deprecation warnings to address in [LOG_PATH], and 4) A step-by-step rollout strategy for [ENVIRONMENT]. Provide the output as a structured report with sections for each step and clear commands the team can execute in order. Include rollback instructions in case of failure.

Example Output

### Rails 7.0 → 8.1 Upgrade Plan for Acme Corp's E-Commerce Platform

**Project Path:** `/var/www/acme-ecommerce`
**Gemfile Path:** `/var/www/acme-ecommerce/Gemfile`
**Config Path:** `/var/www/acme-ecommerce/config/`
**Log Path:** `/var/www/acme-ecommerce/log/upgrade_rails8.1.log`
**Target Environment:** Staging (production upgrade scheduled for next maintenance window)

---

#### 1. Dependency Updates (Gemfile)
**Current Rails Version:** 7.0.8
**Target Rails Version:** 8.1.0

```ruby
# Gemfile updates required:
gem 'rails', '~> 8.1.0'

# Critical dependency changes:
gem 'bootsnap', '>= 1.17.0'  # Required for Rails 8.1
# Note: 'sprockets-rails' must be removed (deprecated in Rails 8.1)
gem 'importmap-rails', '>= 2.0'  # Required for asset pipeline changes
gem 'turbo-rails', '>= 2.0.0'   # Updated for Hotwire integration
```

Run: `bundle update rails bootsnap importmap-rails turbo-rails`

#### 2. Configuration Changes
**Required Updates:**
- **config/application.rb:** Add `config.load_defaults 8.1`
- **config/environments/production.rb:** Set `config.assets.compile = false` (Rails 8.1 enforces this)
- **config/initializers/new_framework_defaults_8_1.rb:** Generate this file and review all deprecation warnings

#### 3. Deprecation Warnings to Address
From the upgrade log (`/var/www/acme-ecommerce/log/upgrade_rails8.1.log`):
- **WARNING:** `config.action_controller.page_cache_directory` is deprecated. Use `config.public_file_server.cache_control` instead.
- **WARNING:** `ActiveRecord::Base.pluralize_table_names` is now default `false`. Review model names.
- **WARNING:** `ActionController::Parameters` no longer permits unpermitted keys by default. Update strong parameters in controllers.

#### 4. Rollout Strategy
**Phase 1: Staging (This Week)**
1. Commit dependency updates to a new branch: `git checkout -b rails-8.1-upgrade`
2. Run `rails app:update` to generate upgrade files
3. Fix deprecation warnings identified in logs
4. Run test suite: `bundle exec rspec` (Expected: 100% pass rate)
5. Deploy to staging and validate critical user flows (checkout, admin panel)

**Phase 2: Production (Next Maintenance Window)**
1. Freeze new deployments 2 hours before upgrade
2. Run `rails db:migrate` in a maintenance window
3. Monitor performance metrics for 24 hours
4. Rollback plan: Revert to previous commit if error rate exceeds 1% or response time increases >20%

---

**Next Steps:**
- [ ] Create upgrade branch and commit initial changes
- [ ] Schedule staging deployment with QA team
- [ ] Reserve production maintenance window (30 minutes)
- [ ] Prepare rollback script: `git reset --hard HEAD~1 && bundle install && rails db:migrate:redo`

**Estimated Downtime:** 15 minutes (production)
**Risk Level:** Medium (test coverage is 95%)