OpenAEC-Foundation/frappe-agent-migrator

Version Migration Assistant

Systematically plans and executes Frappe/ERPNext version migrations by analyzing breaking changes, scanning custom code for compatibility issues, and generating migration plans.

Purpose: Prevent failed migrations by detecting every breaking change BEFORE upgrading.

When to Use This Agent

MIGRATION TRIGGER
|
+-- Planning a version upgrade
|   "We need to go from v14 to v15"
|   --> USE THIS AGENT
|
+-- Post-upgrade errors
|   "Everything broke after bench update"
|   --> USE THIS AGENT (Step 2-5 for diagnosis)
|
+-- Checking custom app compatibility
|   "Will our custom app work on v16?"
|   --> USE THIS AGENT (Step 3 for code scan)
|
+-- Already mid-migration with issues
|   "bench migrate fails with errors"
|   --> USE THIS AGENT + frappe-agent-debugger

Migration Workflow

STEP 1: IDENTIFY MIGRATION PATH
  Source version → Target version (NEVER skip major versions)

STEP 2: CHECK BREAKING CHANGES
  Apply breaking changes database for each version jump

STEP 3: SCAN CUSTOM CODE
  Grep for deprecated patterns in all custom apps

STEP 4: GENERATE MIGRATION PLAN
  Backup → Staging → Test → Production sequence

STEP 5: GENERATE PATCH LIST
  Specific code changes needed per custom app

See references/workflow.md for detailed steps.

Step 1: Migration Path Rules

NEVER skip major versions. ALWAYS migrate sequentially:

| Source | Target | Path | |--------|--------|------| | v14 | v15 | v14 → v15 | | v14 | v16 | v14 → v15 → v16 | | v15 | v16 | v15 → v16 |

Version Identification

# Check current versions
bench version
# Output shows: frappe X.Y.Z, erpnext X.Y.Z

# Check available versions
cd apps/frappe && git tag | grep "^v1[456]" | tail -5

Step 2: Breaking Changes Summary

v14 → v15 Breaking Changes

| Category | Change | Impact | Detection Pattern | |----------|--------|--------|-------------------| | Scheduler | Tick interval 240s → 60s | Jobs may run more frequently | Review scheduler_events | | Background Jobs | job_id deduplication added | Duplicate jobs now prevented | Check frappe.enqueue() calls | | Web Views | Workspace replaces Module Def pages | Custom module pages break | Grep for Module Def references | | Print Format | HTML to PDF engine changes | Print layout differences | Test all print formats | | Database | MariaDB 10.6+ required | Server prerequisite | Check mysql --version | | Python | Python 3.10+ required | Syntax/library compatibility | Check python3 --version | | API | frappe.client.get_list signature change | Custom API calls may fail | Grep for frappe.client.get_list | | Permissions | Stricter permission checks on API | Guest access may break | Check allow_guest=True usage | | Assets | New frontend build system | Custom JS bundles may break | Test bench build | | Hooks | boot_session hook changes | Custom boot data may fail | Grep for boot_session | | Naming | Some naming series changes | Document names may differ | Review autoname settings | | Report | Report Builder changes | Custom reports may need updates | Test all Script Reports |

v15 → v16 Breaking Changes

| Category | Change | Impact | Detection Pattern | |----------|--------|--------|-------------------| | DocType Extension | extend_doctype_class replaces doc_events override | Controller overrides need refactoring | Grep for doc_events with method override | | Type Annotations | Type hints now best practice | Code style change | Not breaking, but recommended | | Chrome PDF | New PDF engine (Chrome-based) | Print format rendering changes | Test all print formats | | Data Masking | New privacy feature | PII fields need configuration | Review sensitive fields | | UUID Naming | New uuid naming rule | Naming logic changes | Check autoname settings | | Python | Python 3.11+ required | Library compatibility | Check python3 --version | | Node.js | Node 18+ required | Build system prerequisite | Check node --version | | Redis | Redis 7+ required | Cache/queue compatibility | Check redis-server --version | | Deprecated APIs | Several APIs removed | Code using removed APIs fails | See breaking-changes.md | | Workflow | Workflow engine updates | Custom workflow states may need review | Test all workflows | | Portal | Portal page rendering changes | Custom portal pages may break | Test all portal pages | | Background Jobs | RQ version upgrade | Job serialization changes | Test background jobs |

See references/breaking-changes.md for complete details.

Step 3: Deprecated Pattern Detection

ALWAYS scan custom app code for these patterns:

v14 → v15 Deprecated Patterns

# Run these grep commands in apps/{your_app}/ directory:

# 1. Old-style module page references
grep -rn "Module Def" --include="*.py" --include="*.json"

# 2. Old scheduler API
grep -rn "frappe.utils.scheduler" --include="*.py"

# 3. Deprecated client API
grep -rn "frappe.set_route\|cur_page\|page_container" --include="*.js"

# 4. Old-style print format
grep -rn "frappe.get_print\|standard_format" --include="*.py"

# 5. Deprecated database methods
grep -rn "frappe.db.sql_list\|frappe.db.sql_ddl" --include="*.py"

v15 → v16 Deprecated Patterns

# Run these grep commands in apps/{your_app}/ directory:

# 1. doc_events that should use extend_doctype_class
grep -rn "doc_events" hooks.py

# 2. Old-style controller override
grep -rn "override_doctype_class" --include="*.py"

# 3. Deprecated frappe.utils methods
grep -rn "frappe.utils.now_datetime\b" --include="*.py"

# 4. Old print format API
grep -rn "frappe.utils.pdf\|get_pdf" --include="*.py"

# 5. Removed API calls
grep -rn "frappe.get_hooks\b.*boot_session" --include="*.py"

# 6. Missing type annotations (warning, not error)
grep -rn "def .*whitelist" --include="*.py"

Step 4: Migration Plan Template

ALWAYS generate a migration plan in this format:

## Migration Plan: v{source} → v{target}

### Prerequisites
- [ ] Python version: {required}
- [ ] Node.js version: {required}
- [ ] MariaDB version: {required}
- [ ] Redis version: {required}
- [ ] Disk space: minimum 2x current DB size

### Phase 1: Preparation (Day 1)
1. Full backup: `bench --site {site} backup --with-files`
2. Document current state: `bench version > pre-migration-versions.txt`
3. List all custom apps: `bench --site {site} list-apps`
4. Run deprecated pattern scan (Step 3)
5. Fix all detected issues in custom apps

### Phase 2: Staging (Day 2-3)
1. Clone production to staging environment
2. Restore backup on staging: `bench --site staging restore {backup}`
3. Switch branch: `bench switch-to-branch version-{target} frappe erpnext`
4. Run migration: `bench --site staging migrate`
5. Run full test suite on staging

### Phase 3: Testing (Day 4-5)
- [ ] All DocTypes load correctly
- [ ] All print formats render correctly
- [ ] All workflows transition correctly
- [ ] All scheduled jobs execute correctly
- [ ] All custom reports generate correctly
- [ ] All API endpoints respond correctly
- [ ] All user permissions work correctly
- [ ] Performance is acceptable (page load < 3s)

### Phase 4: Production (Day 6)
1. Schedule maintenance window
2. Enable maintenance mode: `bench --site {site} set-maintenance-mode on`
3. Final backup: `bench --site {site} backup --with-files`
4. Switch branch: `bench switch-to-branch version-{target} frappe erpnext`
5. Run migration: `bench --site {site} migrate`
6. Run `bench build --production`
7. Restart: `bench restart` (or `sudo supervisorctl restart all`)
8. Disable maintenance mode: `bench --site {site} set-maintenance-mode off`
9. Verify (Phase 3 checklist again)

### Rollback Plan
1. Stop all services: `sudo supervisorctl stop all`
2. Restore backup: `bench --site {site} restore {backup_path}`
3. Switch back: `bench switch-to-branch version-{source} frappe erpnext`
4. Run migration: `bench --site {site} migrate`
5. Rebuild: `bench build --production`
6. Restart: `sudo supervisorctl restart all`

Step 5: Custom App Patch List

For each deprecated pattern found in Step 3, generate a specific fix:

| File | Line | Current Code | Required Change | Breaking? | |------|------|-------------|-----------------|-----------| | {file} | {line} | {old_pattern} | {new_pattern} | Yes/No |

Common Patches (v14 → v15)

| Pattern | Replace With | |---------|-------------| | frappe.db.sql_list(...) | frappe.db.get_all(..., pluck="name") | | Module Def page references | Workspace configuration | | cur_page JS references | frappe.router API | | Old scheduler tick assumptions | Review timing for 60s interval |

Common Patches (v15 → v16)

| Pattern | Replace With | |---------|-------------| | doc_events controller override | extend_doctype_class in hooks.py | | Missing super() in overrides | Add super().method() call | | frappe.utils.pdf.get_pdf() | Updated PDF API | | No type annotations | Add type hints to public methods |

Agent Output Format

ALWAYS produce migration output in this format:

## Migration Assessment

### Version Path
{source} → {target} (via {intermediate versions if any})

### Prerequisites Status
| Requirement | Current | Required | Status |
|-------------|---------|----------|--------|
| Python | {ver} | {ver} | OK/FAIL |
| Node.js | {ver} | {ver} | OK/FAIL |
| MariaDB | {ver} | {ver} | OK/FAIL |

### Breaking Changes Found: {count}
[List from Step 2]

### Custom Code Issues Found: {count}
[Table from Step 3 scan]

### Migration Plan
[From Step 4]

### Patch List
[From Step 5]

### Risk Assessment
| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|

### Estimated Timeline
Preparation: {days} | Staging: {days} | Testing: {days} | Production: {hours}

### Referenced Skills
- `frappe-ops-upgrades`: Version upgrade procedures
- `frappe-ops-backup`: Backup and restore
- `frappe-agent-debugger`: For post-migration error diagnosis

See references/checklists.md for complete migration checklists. See references/breaking-changes.md for full breaking changes database.