Skill Rails Upgrade

1---
2name: skill-rails-upgrade
3description: "Analyze Rails apps and provide upgrade assessments"
4source: "https://github.com/robzolkos/skill-rails-upgrade"
5risk: safe
6---
7 
8## When to Use This Skill
9 
10Analyze Rails apps and provide upgrade assessments
11 
12Use this skill when working with analyze rails apps and provide upgrade assessments.
13# Rails Upgrade Analyzer
14 
15Analyze the current Rails application and provide a comprehensive upgrade assessment with selective file merging.
16 
17## Step 1: Verify Rails Application
18 
19Check that we're in a Rails application by looking for these files:
20- `Gemfile` (must exist and contain 'rails')
21- `config/application.rb` (Rails application config)
22- `config/environment.rb` (Rails environment)
23 
24If any of these are missing or don't indicate a Rails app, stop and inform the user this doesn't appear to be a Rails application.
25 
26## Step 2: Get Current Rails Version
27 
28Extract the current Rails version from:
291. First, check `Gemfile.lock` for the exact installed version (look for `rails (x.y.z)`)
302. If not found, check `Gemfile` for the version constraint
31 
32Report the exact current version (e.g., `7.1.3`).
33 
34## Step 3: Find Latest Rails Version
35 
36Use the GitHub CLI to fetch the latest Rails release:
37 
38```bash
39gh api repos/rails/rails/releases/latest --jq '.tag_name'
40```
41 
42This returns the latest stable version tag (e.g., `v8.0.1`). Strip the 'v' prefix for comparison.
43 
44Also check recent tags to understand the release landscape:
45 
46```bash
47gh api repos/rails/rails/tags --jq '.[0:10] | .[].name'
48```
49 
50## Step 4: Determine Upgrade Type
51 
52Compare current and latest versions to classify the upgrade:
53 
54- **Patch upgrade**: Same major.minor, different patch (e.g., 7.1.3 → 7.1.5)
55- **Minor upgrade**: Same major, different minor (e.g., 7.1.3 → 7.2.0)
56- **Major upgrade**: Different major version (e.g., 7.1.3 → 8.0.0)
57 
58## Step 5: Fetch Upgrade Guide
59 
60Use WebFetch to get the official Rails upgrade guide:
61 
62URL: `https://guides.rubyonrails.org/upgrading_ruby_on_rails.html`
63 
64Look for sections relevant to the version jump. The guide is organized by target version with sections like:
65- "Upgrading from Rails X.Y to Rails X.Z"
66- Breaking changes
67- Deprecation warnings
68- Configuration changes
69- Required migrations
70 
71Extract and summarize the relevant sections for the user's specific upgrade path.
72 
73## Step 6: Fetch Rails Diff
74 
75Use WebFetch to get the diff between versions from railsdiff.org:
76 
77URL: `https://railsdiff.org/{current_version}/{target_version}`
78 
79For example: `https://railsdiff.org/7.1.3/8.0.0`
80 
81This shows:
82- Changes to default configuration files
83- New files that need to be added
84- Modified initializers
85- Updated dependencies
86- Changes to bin/ scripts
87 
88Summarize the key file changes.
89 
90## Step 7: Check JavaScript Dependencies
91 
92Rails applications often include JavaScript packages that should be updated alongside Rails. Check for and report on these dependencies.
93 
94### 7.1: Identify JS Package Manager
95 
96Check which package manager the app uses:
97 
98```bash
99# Check for package.json (npm/yarn)
100ls package.json 2>/dev/null
101 
102# Check for importmap (Rails 7+)
103ls config/importmap.rb 2>/dev/null
104```
105 
106### 7.2: Check Rails-Related JS Packages
107 
108If `package.json` exists, check for these Rails-related packages:
109 
110```bash
111# Extract current versions of Rails-related packages
112cat package.json | grep -E '"@hotwired/|"@rails/|"stimulus"|"turbo-rails"' || echo "No Rails JS packages found"
113```
114 
115**Key packages to check:**
116 
117| Package | Purpose | Version Alignment |
118|---------|---------|-------------------|
119| `@hotwired/turbo-rails` | Turbo Drive/Frames/Streams | Should match Rails version era |
120| `@hotwired/stimulus` | Stimulus JS framework | Generally stable across Rails versions |
121| `@rails/actioncable` | WebSocket support | Should match Rails version |
122| `@rails/activestorage` | Direct uploads | Should match Rails version |
123| `@rails/actiontext` | Rich text editing | Should match Rails version |
124| `@rails/request.js` | Rails UJS replacement | Should match Rails version era |
125 
126### 7.3: Check for Updates
127 
128For npm/yarn projects, check for available updates:
129 
130```bash
131# Using npm
132npm outdated @hotwired/turbo-rails @hotwired/stimulus @rails/actioncable @rails/activestorage 2>/dev/null
133 
134# Or check latest versions directly
135npm view @hotwired/turbo-rails version 2>/dev/null
136npm view @rails/actioncable version 2>/dev/null
137```
138 
139### 7.4: Check Importmap Pins (if applicable)
140 
141If the app uses importmap-rails, check `config/importmap.rb` for pinned versions:
142 
143```bash
144cat config/importmap.rb | grep -E 'pin.*turbo|pin.*stimulus|pin.*@rails' || echo "No importmap pins found"
145```
146 
147To update importmap pins:
148```bash
149bin/importmap pin @hotwired/turbo-rails
150bin/importmap pin @hotwired/stimulus
151```
152 
153### 7.5: JS Dependency Summary
154 
155Include in the upgrade summary:
156 
157```
158### JavaScript Dependencies
159 
160**Package Manager**: [npm/yarn/importmap/none]
161 
162| Package | Current | Latest | Action |
163|---------|---------|--------|--------|
164| @hotwired/turbo-rails | 8.0.4 | 8.0.12 | Update recommended |
165| @rails/actioncable | 7.1.0 | 8.0.0 | Update with Rails |
166| ... | ... | ... | ... |
167 
168**Recommended JS Updates:**
169- Run `npm update @hotwired/turbo-rails` (or yarn equivalent)
170- Run `npm update @rails/actioncable @rails/activestorage` to match Rails version
171```
172 
173---
174 
175## Step 8: Generate Upgrade Summary
176 
177Provide a comprehensive summary including all findings from Steps 1-7:
178 
179### Version Information
180- Current version: X.Y.Z
181- Latest version: A.B.C
182- Upgrade type: [Patch/Minor/Major]
183 
184### Upgrade Complexity Assessment
185 
186Rate the upgrade as **Small**, **Medium**, or **Large** based on:
187 
188| Factor | Small | Medium | Large |
189|--------|-------|--------|-------|
190| Version jump | Patch only | Minor version | Major version |
191| Breaking changes | None | Few, well-documented | Many, significant |
192| Config changes | Minimal | Moderate | Extensive |
193| Deprecations | None active | Some to address | Many requiring refactoring |
194| Dependencies | Compatible | Some updates needed | Major dependency updates |
195 
196### Key Changes to Address
197 
198List the most important changes the user needs to handle:
1991. Configuration file updates
2002. Deprecated methods/features to update
2013. New required dependencies
2024. Database migrations needed
2035. Breaking API changes
204 
205### Recommended Upgrade Steps
206 
2071. Update test suite and ensure passing
2082. Review deprecation warnings in current version
2093. Update Gemfile with new Rails version
2104. Run `bundle update rails`
2115. Update JavaScript dependencies (see JS Dependencies section)
2126. **DO NOT run `rails app:update` directly** - use the selective merge process below
2137. Run database migrations
2148. Run test suite
2159. Review and update deprecated code
216 
217### Resources
218 
219- Rails Upgrade Guide: https://guides.rubyonrails.org/upgrading_ruby_on_rails.html
220- Rails Diff: https://railsdiff.org/{current}/{target}
221- Release Notes: https://github.com/rails/rails/releases/tag/v{target}
222 
223---
224 
225 
226## When to Use This Skill
227 
228Analyze Rails apps and provide upgrade assessments
229 
230Use this skill when working with analyze rails apps and provide upgrade assessments.
231## Step 9: Selective File Update (replaces `rails app:update`)
232 
233**IMPORTANT:** Do NOT run `rails app:update` as it overwrites files without considering local customizations. Instead, follow this selective merge process:
234 
235### 9.1: Detect Local Customizations
236 
237Before any upgrade, identify files with local customizations:
238 
239```bash
240# Check for uncommitted changes
241git status
242 
243# List config files that differ from a fresh Rails app
244# These are the files we need to be careful with
245git diff HEAD --name-only -- config/ bin/ public/
246```
247 
248Create a mental list of files in these categories:
249- **Custom config files**: Files with project-specific settings (i18n, mailer, etc.)
250- **Modified bin scripts**: Scripts with custom behavior (bin/dev with foreman, etc.)
251- **Standard files**: Files that haven't been customized
252 
253### 9.2: Analyze Required Changes from Railsdiff
254 
255Based on the railsdiff output from Step 6, categorize each changed file:
256 
257| Category | Action | Example |
258|----------|--------|---------|
259| **New files** | Create directly | `config/initializers/new_framework_defaults_X_Y.rb` |
260| **Unchanged locally** | Safe to overwrite | `public/404.html` (if not customized) |
261| **Customized locally** | Manual merge needed | `config/application.rb`, `bin/dev` |
262| **Comment-only changes** | Usually skip | Minor comment updates in config files |
263 
264### 9.3: Create Upgrade Plan
265 
266Present the user with a clear upgrade plan:
267 
268```
269## Upgrade Plan: Rails X.Y.Z → A.B.C
270 
271### New Files (will be created):
272- config/initializers/new_framework_defaults_A_B.rb
273- bin/ci (new CI script)
274 
275### Safe to Update (no local customizations):
276- public/400.html
277- public/404.html
278- public/500.html
279 
280### Needs Manual Merge (local customizations detected):
281- config/application.rb
282  └─ Local: i18n configuration
283  └─ Rails: [describe new Rails changes if any]
284 
285- config/environments/development.rb
286  └─ Local: letter_opener mailer config
287  └─ Rails: [describe new Rails changes]
288 
289- bin/dev
290  └─ Local: foreman + Procfile.dev setup
291  └─ Rails: changed to simple ruby script
292 
293### Skip (comment-only or irrelevant changes):
294- config/puma.rb (only comment changes)
295```
296 
297### 9.4: Execute Upgrade Plan
298 
299After user confirms the plan:
300 
301#### For New Files:
302Create them directly using the content from railsdiff or by extracting from a fresh Rails app:
303 
304```bash
305# Generate a temporary fresh Rails app to extract new files
306cd /tmp && rails new rails_template --skip-git --skip-bundle
307# Then copy needed files
308```
309 
310Or use the Rails generator for specific files:
311```bash
312bin/rails app:update:configs  # Only updates config files, still interactive
313```
314 
315#### For Safe Updates:
316Overwrite these files as they have no local customizations.
317 
318#### For Manual Merges:
319For each file needing merge, show the user:
320 
3211. **Current local version** (their customizations)
3222. **New Rails default** (from railsdiff)
3233. **Suggested merged version** that:
324   - Keeps all local customizations
325   - Adds only essential new Rails functionality
326   - Removes deprecated settings
327 
328Example merge for `config/application.rb`:
329```ruby
330# KEEP local customizations:
331config.i18n.available_locales = [:de, :en]
332config.i18n.default_locale = :de
333config.i18n.fallbacks = [:en]
334 
335# ADD new Rails 8.1 settings if needed:
336# (usually none required - new defaults come via new_framework_defaults file)
337```
338 
339### 9.5: Handle Active Storage Migrations
340 
341After file updates, run any new migrations:
342 
343```bash
344bin/rails db:migrate
345```
346 
347Check for new migrations that were added:
348```bash
349ls -la db/migrate/ | tail -10
350```
351 
352### 9.6: Verify Upgrade
353 
354After completing the merge:
355 
3561. Start the Rails server and check for errors:
357   ```bash
358   bin/dev  # or bin/rails server
359   ```
360 
3612. Check the Rails console:
362   ```bash
363   bin/rails console
364   ```
365 
3663. Run the test suite:
367   ```bash
368   bin/rails test
369   ```
370 
3714. Review deprecation warnings in logs
372 
373---
374 
375## Step 10: Finalize Framework Defaults
376 
377After verifying the app works:
378 
3791. Review `config/initializers/new_framework_defaults_X_Y.rb`
3802. Enable each new default one by one, testing after each
3813. Once all defaults are enabled and tested, update `config/application.rb`:
382   ```ruby
383   config.load_defaults X.Y  # Update to new version
384   ```
3854. Delete the `new_framework_defaults_X_Y.rb` file
386 
387---
388 
389 
390## When to Use This Skill
391 
392Analyze Rails apps and provide upgrade assessments
393 
394Use this skill when working with analyze rails apps and provide upgrade assessments.
395## Error Handling
396 
397- If `gh` CLI is not authenticated, instruct the user to run `gh auth login`
398- If railsdiff.org doesn't have the exact versions, try with major.minor.0 versions
399- If the app is already on the latest version, congratulate the user and note any upcoming releases
400- If local customizations would be lost, ALWAYS stop and show the user what would be overwritten before proceeding
401 
402## Key Principles
403 
4041. **Never overwrite without checking** - Always check for local customizations first
4052. **Preserve user intent** - Local customizations exist for a reason
4063. **Minimal changes** - Only add what's necessary for the new Rails version
4074. **Transparency** - Show the user exactly what will change before doing it
4085. **Reversibility** - User should be able to `git checkout` to restore if needed
409