Rails 8.1 Migration Checklist

Test Coverage Audit

• Run test suite and document baseline (all tests passing)
• Measure current test coverage: ______%
• Target coverage before upgrade: >80%
• Identify critical paths without tests
• Add missing test coverage for critical features
• Document any known test failures or flaky tests

Dependency Analysis

• List all gems in Gemfile with versions
• Check Rails 8.1 compatibility for each gem on GitHub issues
• Identify gems that need updates
• Identify gems that may need alternatives
• Review Gemfile.lock for indirect dependencies
• Document any custom monkey patches or Rails extensions

Gems Requiring Attention:

Breaking Changes Impact

• Review Action Dispatch parameter parsing changes
• Audit MySQL unsigned_float and unsigned_decimal usage
• Check Active Storage Azure configuration
• Review Active Job enqueue_after_transaction_commit usage
• Assess schema.rb alphabetical sorting impact
• Document all affected code locations

Development Environment

• Create new branch: upgrade/rails-8-1
• Backup database: pg_dump / mysqldump
• Update Gemfile: gem 'rails', '~> 8.1.0'
• Update Rails: bundle update rails
• Update all gems: bundle update
• Run bin/rails app:update (interactive)
• Review and merge configuration changes
• Run bin/rails db:migrate

Configuration Updates

• Review config/application.rb changes
• Review config/environments/*.rb changes
• Update .gitattributes for schema.rb normalization
• Review config/initializers for deprecation warnings
• Update config/database.yml if using Azure storage

.gitattributes update:

db/schema.rb merge=union

Automated Testing

• Run full test suite: bin/rails test (or bundle exec rspec)
• Document all test failures
• Fix compatibility issues
• Re-run tests until all pass
• Check for deprecation warnings in logs
• Run linter/static analysis: bundle exec rubocop
• Run security audit: bundle exec brakeman

Manual Testing Checklist

• User authentication/login flows
• Critical business workflows
• Payment processing (if applicable)
• File uploads (Active Storage)
• Background jobs (Active Job)
• Admin interfaces
• API endpoints (if applicable)
• Email delivery
• Third-party integrations

Performance Baseline

• Measure baseline performance (before upgrade)
  • Response time (p50): _______ ms
  • Response time (p95): _______ ms
  • Requests per second: _______
  • Memory usage: _______ MB
• Run performance tests after upgrade
• Compare before/after metrics
• Investigate any regressions >10%

Staging Environment Preparation

• Deploy to staging environment
• Run database migrations
• Verify all services start successfully
• Check logs for errors/warnings
• Run smoke tests on critical features
• Load test with production-like data volume
• Test with production data snapshot (if safe)

Staging Validation

• Full regression testing
• Cross-browser testing (if web app)
• Mobile responsiveness testing
• Integration testing with external services
• Performance monitoring setup
• Error tracking validation (Sentry, Rollbar, etc.)

Rollback Test

• Document rollback procedure
• Test rollback to Rails 8.0 in staging
• Verify data integrity after rollback
• Document any rollback gotchas

Monitoring Setup

• Configure error tracking (Sentry, Honeybadger, etc.)
• Set up performance monitoring (New Relic, Scout, etc.)
• Configure log aggregation (Papertrail, Datadog, etc.)
• Set up uptime monitoring
• Configure alert thresholds
• Test alert notifications

Database Preparation

• Full database backup (production)
• Test restore procedure
• Estimate migration duration
• Plan for migration downtime (if any)
• Prepare database rollback strategy

Communication Plan

• Notify stakeholders of upgrade schedule
• Prepare status page announcement
• Schedule maintenance window (if needed)
• Prepare internal team communication
• Draft customer notification (if user-facing changes)

Pre-Deployment

• Schedule deployment during low-traffic window
• Confirm all stakeholders are available
• Enable maintenance mode (if applicable)
• Final production database backup
• Scale up infrastructure (if needed for migration)
• Verify monitoring dashboards ready

Deployment Steps

• Deploy code to production
• Run database migrations: bin/rails db:migrate
• Restart application servers
• Clear application cache
• Warm up application cache (if applicable)
• Disable maintenance mode
• Monitor error rates (first 30 minutes)

Post-Deployment Validation

• Verify critical features working
• Check error logs (no unexpected errors)
• Monitor performance metrics
• Test background job processing
• Verify scheduled tasks running
• Check third-party integrations
• Monitor database performance
• Validate asset delivery (CDN)

Quick Wins (Immediate)

Local CI Setup

• Create config/ci.rb configuration
• Test with bin/ci locally
• Update team documentation
• Train developers on usage

Structured Event Reporting

• Configure event subscribers
• Identify key events to track
• Set up event logging/forwarding
• Update monitoring dashboards

Markdown Rendering (if applicable)

• Update controllers using markdown
• Test rendering in development
• Deploy to production

Medium-Term Features

Active Job Continuations

• Identify long-running jobs for conversion
• Refactor jobs to use continuations
• Test with Kamal deployments
• Monitor job resilience improvements

Lexxy Rich Text Editor (if using ActionText)

• Install Lexxy gem
• Configure editor settings
• Update frontend integration
• Train content editors

Strategic Features

Action Push Native (if mobile app exists)

• Set up APNs certificates (iOS)
• Configure FCM credentials (Android)
• Install action_push_native gem
• Implement notification sending
• Test on iOS and Android devices

Active Record Tenanting (if multi-tenant needed)

• Design tenant data model
• Configure tenant resolver
• Migrate existing data
• Test tenant isolation
• Deploy incrementally

Turbo Offline (if offline capability needed)

• Design offline data strategy
• Implement service workers
• Configure data synchronization
• Test offline scenarios
• Deploy to production

Initial Monitoring

• Daily error rate review
• Daily performance metrics check
• Background job success rate tracking
• User feedback monitoring
• Critical feature validation

Ongoing Monitoring

• Regular metrics review
• Identify any new patterns/issues
• Performance optimization opportunities
• Cost analysis (infrastructure, CI, etc.)

Developer Training Topics

• Rails 8.1 new features overview
• Active Job Continuations usage
• Local CI workflow
• Structured Event Reporting
• Breaking changes awareness
• Troubleshooting common issues

Documentation Updates

• Update README with Rails 8.1 info
• Update development setup guide
• Update deployment procedures
• Create Rails 8.1 feature guides
• Update coding standards/conventions

Stakeholder Approval

• Technical Lead approval
• Engineering Manager approval
• Product Manager approval (if user-facing changes)
• DevOps/SRE approval
• QA/Test Lead approval

Final Checklist

• All tests passing in production
• Monitoring shows normal metrics
• No critical issues reported
• Team trained on new features
• Documentation updated
• Rollback procedure documented and tested