/frappe-agent-migrator

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, upgrade ERPNext, version change breaks, after update errors, deprecated method..
license: MIT
compatibility: "Claude Code, Claude.ai Projects, Claude API. Frappe v14-v16."
metadata:
  author: OpenAEC-Foundation
  version: "2.0"

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](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](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.sq