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

workflows/09-generate-app-update-preview-workflow.md

View on GitHub
# Workflow 09: Generate app:update Preview

**Purpose:** Generate a preview of what `rails app:update` will change in configuration files

**When to use:** After the codebase was analyzed and the breaking changes report was generated

---

## Inputs

- Target Rails version known
- User's current configuration files accessible
- Version guide available
- `templates/app-update-preview-template.md`
- Detection findings (from Workflow 05)

## Outputs

- **Deliverable #2: app:update Preview.** A preview showing exact configuration file changes (OLD vs NEW), a list of new files that will be created, and a per-file impact assessment (HIGH / MEDIUM / LOW).

## Gates (must be true before the next workflow that runs)

- Preview built from `templates/app-update-preview-template.md`, every placeholder replaced by actual values
- Diffs based on the user's real current config files, not generic examples
- Preview delivered

---

## Step-by-Step Workflow

### Step 1: Identify Configuration Files

Standard Rails configuration files that may change:

```
config/
├── application.rb
├── boot.rb
├── environment.rb
├── environments/
│   ├── development.rb
│   ├── production.rb
│   └── test.rb
├── initializers/
│   ├── assets.rb
│   ├── content_security_policy.rb
│   ├── filter_parameter_logging.rb
│   ├── inflections.rb
│   └── new_framework_defaults_{version}.rb
├── database.yml
├── storage.yml
├── cable.yml
├── puma.rb
└── routes.rb

bin/
├── rails
├── rake
├── setup
└── dev

Gemfile
```

---

### Step 2: Read Current Configuration

For each configuration file:

```
Read: config/application.rb
Read: config/environments/production.rb
Read: config/environments/development.rb
Read: config/environments/test.rb
Read: config/database.yml
Read: Gemfile
```

Store current contents for comparison.

---

### Step 3: Load Version Guide

Read version-specific configuration changes:

```
Read: version-guides/upgrade-{FROM}-to-{TO}.md
```

Extract the configuration section that details:
- New default settings
- Changed settings
- Removed settings
- New files added

---

### Step 4: Generate File-by-File Preview

For each affected file, create a diff preview:

```markdown
## config/environments/production.rb

### Changes Required

**Line 25: SSL Configuration**

BEFORE:
\```ruby
config.force_ssl = true
\```

AFTER:
\```ruby
config.force_ssl = true
config.assume_ssl = true  # NEW in Rails 8.0
\```

**Impact:** MEDIUM - Required for proper SSL handling with load balancers

---

**Line 48: Cache Store**

BEFORE:
\```ruby
config.cache_store = :redis_cache_store
\```

AFTER:
\```ruby
# Option 1: Keep Redis (recommended if already working)
config.cache_store = :redis_cache_store

# Option 2: Switch to Solid Cache (Rails 8.0 default)
config.cache_store = :solid_cache_store
\```

**Impact:** LOW - Optional change, Redis still supported

⚠️ **Custom Code Warning:** You have Redis-specific configuration in `config/initializers/redis.rb`. Review if switching to Solid Cache.
```

---

### Step 5: List New Files

Files that `rails app:update` will create:

```markdown
## New Files to Be Created

| File | Purpose | Action |
|------|---------|--------|
| `config/initializers/new_framework_defaults_8_0.rb` | Opt-in to new defaults | Review and enable gradually |
| `bin/dev` | Development server script | Review for Procfile compatibility |
| `Dockerfile` | Container configuration | Review if using Docker |
| `config/deploy.yml` | Kamal deployment | Skip if not using Kamal |
| `.github/workflows/ci.yml` | GitHub Actions CI | Review if using GitHub Actions |
```

---

### Step 6: Categorize by Impact

Group changes by impact level:

```markdown
## Impact Summary

### 🔴 HIGH IMPACT (Must Change)
Files that must be updated for the app to work:

1. `Gemfile` - Update Rails version
2. `config/application.rb` - Update load_defaults

### 🟡 MEDIUM IMPACT (Should Change)
Files that should be updated for best practices:

1. `config/environments/production.rb` - SSL configuration
2. `config/database.yml` - Connection pool settings

### 🟢 LOW IMPACT (Optional)
Files that can be updated later:

1. `config/environments/development.rb` - Debug settings
2. `bin/dev` - New development script
```

---

### Step 7: Generate Recommended Approach

```markdown
## Recommended Approach

### Option A: Interactive (Recommended for Complex Apps)

Run `rails app:update` and review each change:

\```bash
rails app:update
\```

For each file, you'll be prompted:
- `Y` - Accept change
- `n` - Skip change
- `d` - View diff
- `q` - Quit

### Option B: Manual (Recommended for Custom Configurations)

Apply changes manually based on this preview:

1. Update `Gemfile` first
2. Run `bundle update rails`
3. Apply HIGH impact changes from this report
4. Run test suite
5. Apply MEDIUM impact changes
6. Run test suite again
7. Optionally apply LOW impact changes

### Option C: Accept All (Only for Simple Apps)

Accept all defaults:

\```bash
rails app:update --force
\```

⚠️ **Warning:** This will overwrite custom configurations. Only use if you have version control and can review changes.
```

---

### Step 8: Add Framework Defaults Guide

```markdown
## New Framework Defaults

After upgrading, Rails creates `config/initializers/new_framework_defaults_{version}.rb`.

This file lets you opt-in to new behaviors gradually:

\```ruby
# config/initializers/new_framework_defaults_8_0.rb

# Don't enable all at once!
# Enable one at a time and test:

# Rails.application.config.active_record.default_column_serializer = JSON
# Rails.application.config.active_support.cache_format_version = 7.1
\```

### Recommended Approach

1. Start with all options commented out
2. Enable one option at a time
3. Run test suite after each
4. Deploy to staging and verify
5. Once all verified, update `config.load_defaults` to {VERSION}
6. Delete the new_framework_defaults file
```

---

### Step 9: Deliver Preview

Present the preview to the user:

```markdown
# app:update Preview for Rails {VERSION}

Here's what will change when you run `rails app:update`:

[PREVIEW CONTENT]

## Quick Start

1. **Review** the HIGH impact changes above
2. **Run** `rails app:update`
3. **Choose** Option A (interactive) for most control
4. **Test** after each major change

Need help with any specific file? Let me know!
```

---

## Preview Quality Standards

### Show Actual Line Numbers

```markdown
**Line 25:** (not just "somewhere in the file")
```

### Provide Both Options When Applicable

```markdown
# Option 1: Keep existing (if it works)
# Option 2: Use new default (recommended)
```

### Flag Custom Code

```markdown
⚠️ **Custom Code Warning:** This file has non-standard configuration
```

### Be Specific About Impact

| Impact | Meaning |
|--------|---------|
| HIGH | App won't start without this change |
| MEDIUM | App works but may have issues |
| LOW | Cosmetic or optional improvements |

---

**Related Files:**
- Template: `templates/app-update-preview-template.md`
- Version guides: `version-guides/upgrade-{FROM}-to-{TO}.md`

---

## Self-review checklist

Before delivering, verify:

- [ ] All {PLACEHOLDERS} replaced with actual values
- [ ] File list matches user's actual config files
- [ ] Diffs based on real current config vs target version
- [ ] Next steps clearly outlined
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