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](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 Pl