Odoo Module Migration Guide: 5 Steps to Flawless Success

This Odoo module migration guide is the essential resource for any Odoo developer looking to adapt existing modules for newer software versions. Mastering the Odoo migration process is crucial for maintaining functionality and keeping pace with the platform’s evolution. This guide will walk you through the entire process, from setting up your environment to submitting your work for review. For a broader understanding of community involvement, you might also want to read our Ultimate OCA Contribution Guide.

An essential task for any Odoo developer is adapting existing modules to work with newer versions of the software. This process, known as module migration, is crucial for maintaining functionality and keeping up with Odoo’s evolution. This guide will walk you through the entire process, from setting up your environment to submitting your work for review.

Why This Odoo Module Migration Guide is Crucial

Each new version of Odoo brings changes to models, fields, and methods. Consequently, you must review these updates to ensure your migrated module functions correctly. For this purpose, the repositories of the Odoo Community Association (OCA) and Open Upgrade are your primary resources for understanding the modifications detailed in this Odoo module migration guide.

Pre-commit hooks are another key element. These are automated scripts that run before every Git commit. As a result, they help ensure code quality and adherence to standards, while also automatically making small necessary changes, like modifying the readme file.

Preparing for Migration: First Steps in Your Odoo Module Migration Guide

First, you need to access the GitHub repository where the module you want to migrate is located. Then, look for open issues related to your target version migration. This will show you which modules are ready to be migrated or are being worked on by others, allowing you to communicate with other contributors.

Next, you should visit the relevant migration instruction page for the Odoo version you are targeting. You can find these in the Open Upgrade repository or the OCA documentation. These instructions are a core part of this Odoo module migration guide.

After that, set up your development environment. This guide uses Visual Studio Code as the code editor. It is also important to set up a Python virtual environment to manage dependencies. Then, clone the Odoo and OCA addons repositories to your local environment. Finally, define the necessary environment variables, such as the location of the repositories and modules.

During the Odoo migration process, you will inevitably face Git merge conflicts. Therefore, understanding these conflicts and how to resolve them is a critical part of the process.

The Core Odoo Module Migration Guide: Code Implementation

To begin this phase of the Odoo module migration, clone the module’s repository. Then, create a new Git branch for your migration work. After that, use Git commands to pull the changes from the target Odoo version.

Subsequently, you will need to identify and fix the code changes. Look for modifications in models, such as added or removed fields, methods, or other structures. You can use tools like Open Upgrade to see the commits made for migrations from previous versions to your target version. This will help you see examples of the necessary code changes. Then, fix any bugs or errors that arise from the version change and adjust the existing tests to match the new code.

Next, update the __manifest__.py file of your module to the target version. For instance, change the version from 16.0 to 17.0.

Finally, run the pre-commit hooks. This step in our Odoo module migration guide ensures the quality of your code and allows the hooks to make any necessary automatic changes.

Submitting and Approving Your Pull Request

First, push your migrated changes to your organization’s repository. Then, create a pull request (PR) to the OCA repository. The module’s maintainer or the Project Steering Committee (PSC) will then review your PR. They will check the code, functionality, and compliance with OCA standards.

Once your PR is approved, a maintainer or a Project Committee Collaborator (PCC) can merge it into the main OCA repository. The ocabot will then upload the migrated module to the relevant OCA repository.

Practical Steps for Your Odoo Module Migration

Here are the practical steps to perform an Odoo module migration, complete with example commands. Following this section of the Odoo module migration guide carefully will ensure a smooth process.

Initial Preparation

1. Select Module & Target Version: First, decide which Odoo module you want to migrate and what your target Odoo version is (e.g., from v16.0 to v17.0).
2. Check Issues on GitHub: Then, visit the relevant OCA repository. Look for an issue with the label [VERSION].0 migration (e.g., 17.0 migration). Check if your module is already listed or if someone else is working on it. If you want to start, comment on the issue to inform the community.
3. Understand Migration Instructions: Next, visit the Open Upgrade repository. Find the migration issue for your target version (e.g., “Migration from 16 to 17”). Read about the changes in models, fields, and methods between the old and new versions. This will give you a guide on the type of code changes you need to make.
4. Set Up Your Development Environment:
   • First, create a working directory for your project.Then, initialize a Python virtual environment.Finally, clone the Odoo and OCA addons repositories.

# Example for creating a virtual environment
mkvenv oca-migration-tutorial
workon oca-migration-tutorial # Activate the virtual environment

# Clone the Odoo and OCA addons repositories (replace URL if necessary)
git clone https://github.com/odoo/odoo.git odoo
git clone https://github.com/OCA/some-oca-addons.git oca-addons

# Install Python dependencies
pip install -r odoo/requirements.txt
pip install -r oca-addons/requirements.txt # If there is a requirements.txt file in the addons

1. Define Environment Variables: In your ~/.bashrc or ~/.zshrc, define the variables that the migration script will use:

# Example environment variables
export OCA_REPO_PATH="/path/to/your/oca-addons"
export MODULE_TO_MIGRATE="project_status" # Example module name
export TARGET_VERSION="17.0"
export YOUR_GITHUB_USERNAME="your-github-username"

Live Migration Demo

• Navigate to the OCA Addons Source Code Directory:

cd oca-addons

• Clone the Module Repository (If Not Already Cloned): If you haven’t cloned the module’s repository yet, do so now:

git clone https://github.com/OCA/project.git # Replace with the appropriate OCA repository

• Create a New Branch for Migration: Go to the directory of the module to be migrated, and then create a new branch based on the previous Odoo version you are migrating from (e.g., 16.0 for a migration to 17.0).

cd project/project_status # Replace with your module path
git checkout 16.0 # Checkout the old version branch
git checkout -b 17.0-migration_project_status # Create a new branch for the migration

• Merge Changes from the Target Odoo Version: Now, merge the changes from the target Odoo version into your migration branch. This will cause conflicts that you must resolve manually.
  • Resolving Conflicts: This is the most critical manual part. When a conflict arises (for instance, a field has been removed, or a method has been changed), you must compare the code from both versions and decide how to adapt your module.
    • Example Conflict: If active_id is changed to id, you must change all references of active_id to id in your module’s code.
    • Viewing Model Changes: To help resolve conflicts and understand the changes, you can look at Open Upgrade or the upgrade scripts in the Odoo repository itself. Look for relevant commits or check the TXT files that detail model changes.
• Update the Manifest File (__manifest__.py): Change the Odoo version in your module’s __manifest__.py file to the target version.

# Example change in __manifest__.py
{
    'name': 'Project Status',
    'version': '17.0.1.0.0', # Update the version
    'category': 'Project',
    # ...
}

• Run Pre-commit Hooks: After adjusting all code and tests, run the pre-commit hooks. This will help format your code and make necessary automatic changes.

pre-commit run --all-files # Run all hooks on all files

• Commit Your Changes:

git add .
git commit -m "\[{TARGET_VERSION}] project_status: migrate to {TARGET_VERSION}"

• Push to Your Organization’s Repository: First, push your branch to your organization’s repository or your personal GitHub account (if you forked it).

git push origin 17.0-migration_project_status

Pull Request Submission and Approval

1. Create a Pull Request (PR):
   • First, open the GitHub page of the relevant OCA repository.
   • Then, you will see an option to create a PR from the branch you just pushed.
   • Provide a clear PR title and a description detailing the changes you have made.
   • Finally, ensure your PR complies with the OCA contribution guidelines.
2. PR Review:
   • A module maintainer or a PSC member will review your PR.
   • They might leave comments or request changes.
   • Do not be discouraged by comments or change requests; this is part of the learning and quality improvement process.
3. PR Merge:
   • After your PR is approved, a maintainer or PCC can merge it into the main OCA repository.
   • OCAbot will then automatically upload the migrated module to the relevant OCA repository.

Important Things to Remember

• Persistence: The migration process can be challenging and requires persistence. Do not give up if you encounter problems or your PR is rejected.
• Communication: Interact actively with the community and maintainers.
• Empathy: Understand that maintainers and reviewers do this work voluntarily, so make the process as easy as possible for them.
• Learning: Every step in this process is an opportunity to learn.
• CLA (Contributor License Agreement): Finally, make sure you have signed the CLA before contributing.