# Cache Busting Deployment Checklist

**Date:** 2026-03-14

## Pre-Deployment Validation

### Automated Checks

Run these commands before deploying:

```bash
# 1. Check for unversioned assets
python3 v2/scripts/dev-helpers/audit-unversioned-assets.py
# Expected: Exit code 0 (may report noscript tags - lower priority)

# 2. Verify version parameters in PHP files
php v2/scripts/dev-helpers/test-cache-busting.php
# Expected: All critical files show ✓

# 3. Test cache busting behavior
./v2/scripts/dev-helpers/test-cache-busting-behavior.sh
# Expected: All tests pass
```

### Manual Checks

- [ ] Verify `.htaccess` changes are committed
- [ ] Verify `v2/base/head.php` has version parameters
- [ ] Verify critical PHP files have version parameters
- [ ] Review changes in git diff

## Deployment Steps

1. **Deploy code changes:**
   - `.htaccess` (cache headers)
   - `v2/base/head.php` (critical CSS versioning)
   - Other PHP files with version parameters

2. **Verify deployment:**
   ```bash
   # Check version parameters in production HTML
   curl -s "https://www.ordio.com/" | grep -o 'output\.min\.css?v=[0-9]*'
   
   # Should show version parameter like: output.min.css?v=1773495141
   ```

3. **Test cache headers:**
   ```bash
   curl -I "https://www.ordio.com/dist/output.min.css?v=test" | grep -i cache-control
   ```

## Post-Deployment Testing

### Immediate Testing (Within 1 Hour)

1. **Make a test CSS change:**
   - Edit a CSS file or touch `dist/output.min.css`
   - Or make a visible CSS change (e.g., change a color)

2. **Test in browser:**
   - Open homepage in Chrome (incognito mode)
   - Open DevTools → Network tab
   - Reload page (normal refresh, not hard refresh)
   - Verify CSS file loads with new version parameter
   - Verify changes appear without hard refresh

3. **Verify in DevTools:**
   - Network tab: Check CSS file has `?v=` parameter
   - Check status code (should be 200, not 304 if version changed)
   - Check Cache-Control header

### Testing Checklist

- [ ] Homepage (`/`) - CSS changes appear without hard refresh
- [ ] Blog post (`/insights/lexikon/*`) - CSS changes appear
- [ ] 404 page - CSS loads correctly
- [ ] Test in Chrome (incognito)
- [ ] Test in Firefox (incognito)
- [ ] Test in Safari (if available)

### Monitoring (First 24 Hours)

- [ ] Monitor error logs for any cache-related issues
- [ ] Check if team reports any styling issues
- [ ] Verify no increase in server load (cache should still work)
- [ ] Check browser console for any errors

## Success Indicators

✅ CSS/JS changes appear without hard refresh
✅ Version parameters present in HTML output
✅ Version parameters update when files change
✅ No increase in server load
✅ No team reports of broken styling

## Rollback Plan

If issues occur after deployment:

1. **Revert `.htaccess` change:**
   ```bash
   git revert <commit-hash>
   # Or manually change must-revalidate back to immutable
   ```

2. **Investigate:**
   - Check if version parameters are working
   - Verify file modification times are correct
   - Check PHP opcache settings (may cache filemtime())

3. **Fix:**
   - Ensure all critical files have version parameters
   - Clear PHP opcache if needed
   - Verify `.htaccess` is being processed

## Troubleshooting

### Issue: Changes Still Require Hard Refresh

**Possible Causes:**
1. PHP opcache caching `filemtime()` results
2. Version parameters not updating
3. Browser cache still serving old version

**Solutions:**
1. Clear PHP opcache: `opcache_reset()` or restart PHP-FPM
2. Verify version parameters in HTML output
3. Test in incognito mode (bypasses browser cache)

### Issue: Version Parameters Not Present

**Possible Causes:**
1. PHP files not updated
2. Deployment didn't include changes
3. Wrong file paths in `filemtime()`

**Solutions:**
1. Run audit script to find missing version parameters
2. Verify deployment included all changes
3. Check file paths are correct

### Issue: Server Load Increased

**Possible Causes:**
1. Cache headers changed behavior
2. Version parameters causing more requests

**Solutions:**
1. Verify cache headers are still working
2. Check cache hit rates
3. Monitor server metrics

## Related Documentation

- `docs/development/CACHE_BUSTING_FIX_SUMMARY.md` - Complete fix summary
- `docs/development/CACHE_BUSTING_TEST_RESULTS.md` - Test results
- `docs/development/CACHE_BUSTING_GUIDE.md` - Implementation guide
- `docs/performance/caching-strategy.md` - Caching strategy