Connected business operations. Flexible deployment.
A practical guide to managing version control for custom Odoo modules during upgrades, covering repository structure, dependency mapping, testing strategies, and risk mitigation for enterprise ERP migrations.
Managing version control for custom code during Odoo upgrades requires a structured approach that isolates custom modules from core system code, maintains clear dependency mappings, and enforces rigorous testing protocols. The primary risk is the loss of custom functionality or data integrity due to untracked changes, incompatible dependencies, or untested API deprecations. By implementing a dedicated Git repository structure for custom modules, establishing a branching strategy aligned with upgrade cycles, and validating all changes in a representative staging environment, organizations can mitigate these risks. This process ensures that custom business logic remains intact, compatible with the target Odoo version, and ready for deployment without disrupting operational continuity.
The foundation of effective version control is separating custom code from the Odoo core. Never commit custom modules to the main Odoo repository. Instead, create a separate Git repository specifically for customizations. This repository should contain all custom modules, including those that extend core functionality, add new features, or modify existing views and models. Each module should have its own directory with a standard Odoo module structure, including the manifest file, Python code, XML views, and security rules. This separation allows for independent versioning, easier backup, and cleaner upgrade processes. It also facilitates collaboration among developers by providing a clear boundary between vendor code and internal customizations.
Organize the custom repository by business domain or functional area to improve navigability and maintenance. For example, create top-level directories for 'sales', 'inventory', 'finance', and 'hr'. Within each domain, place the relevant custom modules. This structure helps developers quickly locate code related to specific business processes. Additionally, include a root-level README file that documents the purpose of the repository, the upgrade process, and any specific conventions used by the development team. This documentation is critical for onboarding new developers and ensuring consistency across the codebase.
A well-defined branching strategy is essential for managing changes during an upgrade. The recommended approach is to use a 'main' branch for the stable, production-ready code and a 'develop' branch for ongoing development. When planning an upgrade, create a new branch from 'main' named 'upgrade-[target-version]'. All changes required for the upgrade, including code modifications, dependency updates, and configuration adjustments, should be made in this branch. This isolates the upgrade work from regular development, reducing the risk of conflicts and ensuring that the production environment remains stable until the upgrade is fully tested and approved.
Merge conflicts are inevitable when upgrading, especially if custom code interacts with core Odoo modules that have changed. To minimize conflicts, keep custom modules as modular as possible and avoid deep inheritance of core models where feasible. When conflicts do occur, resolve them in the upgrade branch and document the resolution. This documentation should explain why the change was made and how it affects the custom functionality. Regularly merge the 'develop' branch into the 'upgrade' branch to keep the upgrade code current with the latest development work. This practice helps identify and resolve conflicts early, rather than facing a large, complex merge at the end of the upgrade cycle.
Custom modules often depend on core Odoo modules or other third-party add-ons. During an upgrade, these dependencies may change, become deprecated, or require different versions. It is critical to maintain an up-to-date dependency map for all custom modules. This map should list each module, its dependencies, and the specific versions of those dependencies required. Use the Odoo manifest file to define dependencies explicitly. Before upgrading, review this map to identify any dependencies that are not supported in the target version. For third-party add-ons, verify with the vendor that a compatible version exists for the target Odoo release. If a dependency is unavailable, plan for code refactoring or alternative solutions.
| Module Name | Dependency | Current Version | Target Version | Compatibility Status | Action Required |
|---|---|---|---|---|---|
| custom_sales | sale | 15.0 | 16.0 | Compatible | None |
| custom_inventory | stock | 15.0 | 16.0 | Deprecated API | Refactor code |
| custom_hr | hr | 15.0 | 16.0 | Compatible | None |
| custom_finance | account | 15.0 | 16.0 | Version Mismatch | Update dependency |
Odoo upgrades often introduce API deprecations or changes in core models and fields. Custom code that relies on deprecated APIs will fail or behave unexpectedly in the new version. To manage this, conduct a thorough code audit before the upgrade. Use static analysis tools to identify calls to deprecated methods or references to removed fields. Refactor the code to use the new APIs or alternative approaches. This process should be done in the upgrade branch and thoroughly tested. Document all changes made due to API deprecations to provide a clear audit trail and facilitate future upgrades. This proactive approach reduces the risk of runtime errors and ensures that custom functionality remains robust.
Manual code audits are time-consuming and prone to errors. Automate the process by integrating static analysis tools into your CI/CD pipeline. These tools can scan the custom code for deprecated APIs, unused imports, and other potential issues. Configure the tools to fail the build if critical issues are detected. This ensures that developers address problems before merging code into the upgrade branch. Automation also provides consistent results and reduces the burden on developers, allowing them to focus on complex refactoring tasks rather than routine checks.
Testing is the most critical step in managing version control during an upgrade. Deploy the custom modules from the upgrade branch to a staging environment that mirrors the production setup. This environment should include the target Odoo version, all required third-party add-ons, and a representative dataset. Run a comprehensive test suite that covers unit tests, integration tests, and end-to-end business process tests. Verify that all custom functionality works as expected, including new features, modified views, and security rules. Pay special attention to areas where API changes were made. Document any defects found and resolve them in the upgrade branch. Only after all tests pass should the code be considered ready for production deployment.
Regression testing ensures that existing functionality is not broken by the upgrade. Create a list of critical business processes that rely on custom modules. For each process, define a set of test cases that validate the expected behavior. Execute these test cases in the staging environment and compare the results with the pre-upgrade baseline. Any discrepancies should be investigated and resolved. This process helps identify subtle bugs that may not be caught by unit tests. It also provides confidence that the upgrade will not disrupt daily operations.
Maintaining detailed documentation is essential for managing version control during upgrades. Document all changes made to custom modules, including the reason for the change, the files affected, and the testing performed. This documentation should be stored in the repository, preferably in a 'docs' directory or as comments in the code. It provides a clear audit trail for future upgrades and helps new developers understand the codebase. Additionally, maintain a changelog for each module that lists all changes, bug fixes, and feature additions. This changelog should be updated with every commit and reviewed during the upgrade process. It serves as a valuable reference for troubleshooting and compliance.
Before deploying the upgraded custom code to production, ensure that a rollback plan is in place. This plan should include a backup of the current production code and database. The backup should be tested to ensure it can be restored successfully. Define clear go/no-go criteria for the deployment, based on the results of the staging tests. If any critical issues are found, halt the deployment and revert to the previous version. After deployment, monitor the system closely for any unexpected behavior. Have a dedicated support team on standby to address any issues that arise. This proactive approach minimizes downtime and ensures a smooth transition to the new version.
After the upgrade is deployed, perform post-deployment validation to confirm that the system is operating correctly. This includes verifying that all custom modules are installed and active, that data integrity is maintained, and that key business processes are functioning as expected. Collect feedback from end-users and address any issues promptly. This validation phase is critical for identifying any remaining problems and ensuring that the upgrade meets business requirements. It also provides an opportunity to fine-tune the system and optimize performance.
Effective version control is not just about the upgrade process; it is about long-term maintainability. Establish governance policies for custom code development, including code review processes, coding standards, and documentation requirements. These policies should be enforced through automated tools and regular audits. Encourage developers to write clean, modular code that is easy to maintain and upgrade. Regularly review the custom codebase to identify technical debt and areas for improvement. This proactive approach reduces the complexity of future upgrades and ensures that the ERP system remains a strategic asset rather than a liability.
Common questions on this topic. Talk to our team for anything specific to your business.
Use a 'main' branch for stable code and a 'develop' branch for ongoing work. Create a separate 'upgrade-[target-version]' branch for all upgrade-related changes. This isolates the upgrade work and reduces the risk of conflicts.
Conduct a code audit to identify deprecated APIs. Refactor the code to use the new APIs or alternative approaches. Test the changes thoroughly in a staging environment before deploying to production.
Yes, always separate custom code from core Odoo. Use a dedicated Git repository for custom modules. This makes it easier to manage, backup, and upgrade customizations without affecting the core system.
Deploy the custom modules to a staging environment that mirrors production. Run a comprehensive test suite, including unit, integration, and end-to-end tests. Verify that all custom functionality works as expected.
Without version control, you risk losing custom functionality, facing untracked changes, and encountering incompatible dependencies. It also makes it difficult to roll back changes or audit the codebase.
Maintain a dependency map for all custom modules. Verify that all dependencies are compatible with the target Odoo version. If a dependency is unavailable, plan for code refactoring or alternative solutions.
Learn how to design manufacturing ERP reporting frameworks that bridge production and finance, enabling faster, data-driven decisions through unified data models and clear governance.
Transform professional services operations by using ERP as a central workflow platform. Learn how to standardize project, financial, and resource processes to achieve scalable, profitable service delivery.
Learn how to create a durable data migration rulebook that ensures data integrity, reduces risk, and accelerates future ERP upgrades or migrations.
Discuss your workflows, modules and deployment options with our team.
Back to resources