frappe-agent-migrator · diff
v2.0 to v2.0
276 added, 7 removed. Audit A to A.
---
name: frappe-agent-migrator
description: >
Use when migrating a Frappe app between major versions, detecting breaking API changes, or resolving post-migration errors.
Prevents failed migrations from undetected deprecated APIs, removed methods, and changed function signatures.
Covers breaking change detection v14-v15-v16, deprecated API mapping, migration checklist, common migration errors, automatic fix suggestions.
Keywords: migration, version upgrade, breaking changes, deprecated API, v14, v15, v16, migrate, compatibility.
license: MIT
compatibility: "Claude Code, Claude.ai Projects, Claude API. Frappe v14-v16."
metadata:
author: OpenAEC-Foundation
version: "2.0"
---
# Version Migration Assistant
- > **STATUS**: Stub - content pending V2.5 development phase.
+ Systematically plans and executes Frappe/ERPNext version migrations by analyzing breaking changes, scanning custom code for compatibility issues, and generating migration plans.
- ## Quick Reference
+ **Purpose**: Prevent failed migrations by detecting every breaking change BEFORE upgrading.
- _Content to be developed._
+ ## When to Use This Agent
- ## Decision Tree
+ ```
+ 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
+ ```
- _Content to be developed._
+ ## Migration Workflow
- ## See Also
+ ```
+ STEP 1: IDENTIFY MIGRATION PATH
+ Source version → Target version (NEVER skip major versions)
- _Cross-references to be added._
+ 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](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
+ ```bash
+ # 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](references/breaking-changes.md) for complete details.
+
+ ## Step 3: Deprecated Pattern Detection
+
+ ALWAYS scan custom app code for these patterns:
+
+ ### v14 → v15 Deprecated Patterns
+
+ ```bash
+ # 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
+
+ ```bash
+ # 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:
+
+ ```markdown
+ ## 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:
+
+ ```markdown
+ ## 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](references/checklists.md) for complete migration checklists.
+ See [references/breaking-changes.md](references/breaking-changes.md) for full breaking changes database.