# Odoo Upgrade Skill

> Expert workflow for Odoo module upgrades (Migration, Refactoring, Resolution).

- Skill: `odoo-ps/odoo-upgrade-skill` (Agent Skill)
- Install (CLI): `npx skillmds@latest add odoo-ps/odoo-upgrade-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/odoo-ps/odoo-upgrade-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: odoo-ps (https://skillmd.com/u/odoo-ps)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/odoo-ps/odoo-upgrade-skill

---


# Odoo Upgrade Workflow Skill

This skill provides a structured, step-by-step process for upgrading Odoo modules between versions.

> [!IMPORTANT]
> **CRITICAL - Feature Reimplementation Rule**:
> If a feature, method, field, model, or functionality was removed or deprecated in the target Odoo version, **do not** simply delete or disable it if it was being used. Instead, you MUST try to **reimplement** it or find an equivalent target Odoo API/mechanism to preserve the business logic and behavior. Do not lose existing functionality during the upgrade.

## 🚀 UPGRADE WORKFLOW (Strict process for EACH module)

Apply this workflow strictly for each module in the list:

### Step 1: Manifest & Preparation
- **Update Version**: Set the version in `__manifest__.py` to `[target_ver].1.0.0`.
- **Atomic Commit**: Commit the version bump immediately:
  - **Message**: `[UPG][[task_id]] <module_name>: bump version to [target_ver].1.0.0`

### Step 2: Automatable Refactoring (XML Views)
- **Convert Views**: Use `odev upgrade-code -V [target_ver] <db> --from [from_ver] --to [target_ver] --glob "<module_name>/**"`. This is the MANDATORY tool for XML migrations.
- **Atomic Commit**: Commit the XML syntax changes:
  - **Message**: `[UPG][[task_id]] <module_name>: adapt XML views to Odoo [target_ver] syntax`

### Step 3: Iterative Resolution (Python, Security & Feature Reimplementation)
- **Fail Fast (Static Validation)**: Before launching Odoo, validate your changes:
  1. Python: `ruff check path/to/file.py --select E999,F821,F822,F405`. DO NOT fix other lint errors.
  2. XML: `xmllint --noout path/to/file.xml`.
- **Run Verification**: Launch `odev run -V [target_ver] <db> -i <module_name> --stop-after-init`.
- **Log Filtering**: If Odoo fails, DO NOT dump the full log. Use `grep -A 10 -B 10 "Traceback" <log_file>` or `tail -n 20` to extract only the relevant error.
- **Data Migration Reflection**: If you modify models (renaming fields, changing types, deleting tables), assess the impact on production data. Use `odoo_upgrade_utils` to create `pre-migrate.py` or `post-migrate.py` if needed.
- **Handling Removed/Deprecated Features**:
  - **REIMPLEMENT**: If a feature, method, field, model, or functionality was removed or deprecated in the target Odoo version, **do not** simply delete or disable it if it was being used. Instead, try to **reimplement** it or find an equivalent target Odoo API/mechanism to preserve the business logic and behavior.
- **If an error occurs (Python, Security, etc.)**:
  1. **SEARCH origin**: Use `git log -S "..."`, `git log -L`, or `grep` in Odoo target source code to find the exact Commit Hash that introduced the Breaking Change.
  2. **FIX**: Correct the code in our module.
  3. **ATOMIC COMMIT**: Make a commit ONLY for this specific fix.
     - **Format**: `[UPG][[task_id]] <module_name>: description`
     - **Body**: You MUST include the Odoo Hash found (made clickable) and a brief explanation of the breaking change. This is MANDATORY as it will be used in the final synchronization step.
- **Repeat** Step 3 until the module installs and runs without errors.

### Step 4: Module Closure
- **Check Progress**: Mark the module as `[x]` in `TASKS.md`.
- **Upgrade Log**: Update `UPGRADE.md` with a technical summary of changes, Odoo SHAs/PRs found, and functional testing scenarios.

### Step 5: Final Validation (Clean Install & Tests) - MANDATORY
A migration is NEVER considered finished by testing only on the current working database. You MUST prove that the module installs "out of the box" on a fresh environment:
1. **Create a fresh DB**: `odev create -f -V [target_ver] <test_db> -i base`.
2. **Install & Test**: Run `odev test -V [target_ver] <test_db> -i <module_name>`.
3. **Handle Failures**: If this command fails, analyze the logs, fix the code, and **RESTART** the verification on a NEW clean database.

### Step 6: Knowledge Base Synchronization (Final Phase)
Once all modules from the list have passed Step 5:
1. **Review History**: Run `git log --grep="\[UPG\]" --reverse` to review all changes and their sources across all upgraded modules.
2. **Update Centralized Knowledge**: For each unique breaking change found in the history:
   - Add/Update the entry in the knowledge table at `[k_path]/<module_name>/[from_ver]_to_[target_ver].md`.
   - Format: `| Title | Explanation | Odoo Commit Hash |`.
3. **Consistency**: Ensure the information in the centralized KB matches your final `UPGRADE.md` findings.

---

## 📝 COMMIT GUIDELINES RECAP
- One commit per discrete fix. **NO MASSIVE COMMITS**.
- **Format**: `[UPG][[task_id]] module_name: Concise description`
- **Body**: Detailed description + **MANDATORY** Source (Odoo Commit SHA made clickable, PR, or Core path).
- **Ruff**: Run `ruff check <file> --select E999,F821,F822,F405` after Python edits. DO NOT fix unrelated style issues.