Upgrade Planning for Magento 2

Master Upgrade Checklist

Pre-Upgrade (2-4 weeks before)

Planning:
- [ ] Review Magento release notes for breaking changes
- [ ] Check PHP version requirements
- [ ] List all custom modules and their compatibility
- [ ] List all third-party modules and vendor support status
- [ ] Estimate effort and timeline
- [ ] Schedule upgrade window
- [ ] Notify stakeholders

Environment:
- [ ] Set up staging environment matching production
- [ ] Copy production data to staging (anonymize if needed)
- [ ] Verify all services running (Redis, Elasticsearch, etc.)
- [ ] Configure monitoring and alerting
- [ ] Test rollback procedure on staging

Code:
- [ ] Create upgrade branch from production
- [ ] Run PHPStan at current level
- [ ] Fix any critical issues
- [ ] Ensure all tests passing
- [ ] Document current baseline metrics

During Upgrade

Execution:
- [ ] Enable maintenance mode
- [ ] Backup database and files
- [ ] Run composer update
- [ ] Resolve any dependency conflicts
- [ ] Run setup:upgrade
- [ ] Run setup:di:compile
- [ ] Run setup:static-content:deploy
- [ ] Clear all caches
- [ ] Disable maintenance mode

Verification:
- [ ] Homepage loads correctly
- [ ] Category pages render
- [ ] Product pages display
- [ ] Add to cart works
- [ ] Checkout completes
- [ ] Admin panel accessible
- [ ] Cron jobs running
- [ ] Email sending works
- [ ] Search functionality works
- [ ] API endpoints responding

Post-Upgrade (1-2 weeks after)

Monitoring:
- [ ] Monitor error rates for 24-48 hours
- [ ] Check performance metrics
- [ ] Review server resource usage
- [ ] Monitor conversion rates
- [ ] Check customer complaints

Cleanup:
- [ ] Remove deprecated code
- [ ] Update documentation
- [ ] Close upgrade tickets
- [ ] Conduct retrospective
- [ ] Plan next upgrade cycle

Version-Specific Checklists

2.4.5 -> 2.4.6 Specific Items

- [ ] Verify PHP 8.1 compatibility
- [ ] Check Elasticsearch 7.17 compatibility
- [ ] Review inventory module changes
- [ ] Test B2B features if applicable
- [ ] Verify payment gateway compatibility

Staging Environment Setup

Match Production Configuration

# Clone production database
mysqldump -h prod-db -u root -p magento > staging-db.sql
mysql -h staging-db -u root -p magento_staging < staging-db.sql

# Update env.php with staging settings
php -r '
$config = include "app/etc/env.php";
$config["db"]["connection"]["default"]["host"] = "staging-db";
$config["db"]["connection"]["default"]["dbname"] = "magento_staging";
file_put_contents("app/etc/env.php", var_export($config, true));
'

# Clear and rebuild cache
php bin/magento cache:flush
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy -f

Environment Variables

# .env.staging
APP_ENV=staging
APP_DEBUG=1
DB_HOST=staging-db
DB_NAME=magento_staging
REDIS_HOST=staging-redis
ELASTICSEARCH_HOST=staging-es

Service Versions

# docker-compose.staging.yml
services:
  php:
    image: php:8.1-fpm
    extensions:
      - redis
      - intl
      - mbstring
      - pdo_mysql
      - soap
      - xsl
      - zip
      - bcmath
      - gd
  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: staging
  elasticsearch:
    image: elasticsearch:7.17.10
  redis:
    image: redis:7.0

Pre-Upgrade Validation

#!/bin/bash
echo "=== Pre-Upgrade Validation ==="

# Check PHP version
php -v | head -1

# Check required extensions
php -m | grep -E 'curl|gd|intl|mbstring|pdo_mysql|xml|xsl|zip|bcmath|soap|redis' | wc -l

# Check MySQL version
mysql -V

# Check Elasticsearch
curl -s localhost:9200 | grep version

# Check Redis
redis-cli ping

# Check disk space
df -h . | tail -1

# Check file permissions
ls -la app/etc/
ls -la pub/
ls -la var/

Load Testing Baseline

# Capture baseline metrics before upgrade
ab -n 1000 -c 10 http://staging.local/
# Requests per second: 150
# Average response time: 65ms
# Failed requests: 0

Rollback Decision Framework

When to Rollback

Immediate Rollback:
- Critical functionality broken (checkout, payment)
- Data corruption detected
- Security vulnerability introduced
- Performance degradation > 50%
- Error rate > 5%

Investigate First:
- Minor UI issues
- Non-critical feature broken
- Performance degradation < 20%
- Intermittent errors

Rollback Procedure

# Step 1: Enable maintenance mode
php bin/magento maintenance:enable

# Step 2: Stop web traffic
sudo systemctl stop nginx

# Step 3: Restore database
mysql -u root -p magento < /backup/pre-upgrade-$(date +%Y%m%d).sql

# Step 4: Restore code
cd /var/www/magento
git checkout production-pre-upgrade

# Step 5: Restore composer.lock
git checkout composer.lock
composer install --no-dev --prefer-dist

# Step 6: Clear caches
php bin/magento cache:flush

# Step 7: Recompile
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy -f

# Step 8: Restart services
sudo systemctl start nginx
sudo systemctl restart php-fpm

# Step 9: Disable maintenance mode
php bin/magento maintenance:disable

# Step 10: Verify
curl -s http://localhost/ | head -20

Database Backup Strategy

# Pre-upgrade backup script
#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/backup/magento"

# Full database backup
mysqldump -u root -p$DB_PASS \
    --single-transaction \
    --routines \
    --triggers \
    magento > $BACKUP_DIR/db-$DATE.sql

# Compress backup
gzip $BACKUP_DIR/db-$DATE.sql

# Backup media files
tar -czf $BACKUP_DIR/media-$DATE.tar.gz pub/media/

# Backup custom code
tar -czf $BACKUP_DIR/code-$DATE.tar.gz app/code/Vendor/

# Verify backup size
du -sh $BACKUP_DIR/*

Rollback Verification

// Rollback verification script
$checks = [
    'Homepage' => 'http://localhost/',
    'Category' => 'http://localhost/catalog.html',
    'Product' => 'http://localhost/product.html',
    'Cart' => 'http://localhost/checkout/cart/',
    'Admin' => 'http://localhost/admin/',
];

foreach ($checks as $name => $url) {
    $response = file_get_contents($url);
    echo "$name: " . (strlen($response) > 0 ? 'OK' : 'FAILED') . "\n";
}

Upgrade Communication Plan

Stakeholder Notification

2 weeks before:
- Email: Upgrade planned, timeline, expected impact
- Meeting: Walk through plan with team

1 week before:
- Email: Final reminder, freeze period begins
- Update: Any changes to plan

Day of upgrade:
- Slack: Real-time status updates
- Email: Completion notification

After upgrade:
- Email: Success confirmation
- Meeting: Retrospective

Role Assignments

Role              | Responsibility
------------------|----------------------------------------
Project Lead      | Overall coordination, decision-making
Lead Developer    | Technical execution, code changes
DBA              | Database backup/restore, data migration
DevOps           | Environment, deployment, monitoring
QA Lead          | Test execution, sign-off
Support Lead     | Customer communication, issue triage

Status Update Template

## Upgrade Status - [Timestamp]

**Phase:** [Pre-Upgrade / During / Post-Upgrade]
**Status:** [On Track / At Risk / Delayed]

**Completed:**
- [x] Backup completed
- [x] Composer update successful
- [x] Database upgrade complete

**In Progress:**
- [ ] Static content deployment
- [ ] Testing critical paths

**Blockers:**
- None

**Next Steps:**
- Run full regression suite
- Performance testing

**ETA:** [Time]

Post-Upgrade Retrospective

Agenda:
1. What went well?
2. What could be improved?
3. What did we learn?
4. Action items for next upgrade

Metrics to Review:
- Total downtime
- Issues encountered
- Time vs estimate
- Test pass rate
- Performance comparison

Documentation Updates

- Update runbook with lessons learned
- Document any custom procedures
- Update monitoring dashboards
- Archive upgrade artifacts
- Update team knowledge base