Odoo OCA Developer

Expert assistant for Odoo module development following OCA conventions and best practices.

Core Capabilities

1. Module Creation

Create new Odoo modules from OCA template with proper structure and conventions.

Quick Start:

python scripts/init_oca_module.py my_module_name --path /path/to/addons --version 17.0

What this provides:

• Complete OCA-compliant directory structure
• Pre-configured __manifest__.py with required keys
• README structure following OCA guidelines
• Proper __init__.py imports
• Example model, view, and security files

Module naming conventions:

• Use singular form: sale_order_import (not sale_orders_import)
• For base modules: prefix with base_ (e.g., base_location_nuts)
• For localization: prefix with l10n_CC_ (e.g., l10n_es_pos)
• For extensions: prefix with parent module (e.g., mail_forward)
• For combinations: Odoo module first (e.g., crm_partner_firstname)

2. Module Structure

Follow OCA conventions strictly. Reference oca_conventions.md for detailed guidelines.

Essential structure:

module_name/
├── __init__.py
├── __manifest__.py
├── models/
│   ├── __init__.py
│   └── <model_name>.py
├── views/
│   └── <model_name>_views.xml
├── security/
│   ├── ir.model.access.csv
│   └── <model_name>_security.xml
├── data/
│   └── <model_name>_data.xml
├── readme/
│   ├── DESCRIPTION.rst
│   ├── USAGE.rst
│   └── CONTRIBUTORS.rst
└── tests/
    ├── __init__.py
    └── test_<feature>.py

Key principles:

• One file per model: models/sale_order.py
• Views match model names: views/sale_order_views.xml
• Demo data has _demo suffix: demo/sale_order_demo.xml
• Migrations in versioned folders: migrations/17.0.1.0.0/

3. OCA Conventions Compliance

manifest.py essentials:

{
    'name': 'Module Name',
    'version': '17.0.1.0.0',  # {odoo}.x.y.z format
    'category': 'Sales',
    'license': 'AGPL-3',  # or LGPL-3
    'author': 'Your Company, Odoo Community Association (OCA)',
    'website': 'https://github.com/OCA/<repository>',
    'depends': ['base', 'sale'],
    'data': [
        'security/ir.model.access.csv',
        'views/model_name_views.xml',
    ],
    'installable': True,
}

Python code structure:

from odoo import api, fields, models, _
from odoo.exceptions import UserError

class SaleOrder(models.Model):
    _inherit = 'sale.order'
    
    # Fields
    custom_field = fields.Char(string="Custom Field")
    
    # Compute methods
    @api.depends('order_line')
    def _compute_total(self):
        for order in self:
            order.total = sum(order.order_line.mapped('price_total'))
    
    # Business methods
    def action_custom(self):
        self.ensure_one()
        # Implementation

XML naming conventions:

• Views: <model_name>_view_<type> (e.g., sale_order_view_form)
• Actions: <model_name>_action (e.g., sale_order_action)
• Menus: <model_name>_menu
• Groups: <model_name>_group_<name>
• Demo: suffix with _demo

4. Module Migration with OpenUpgrade

Migrate modules between Odoo versions following OpenUpgrade patterns. See openupgrade_migration.md for complete guide.

Migration structure:

module_name/
└── migrations/
    └── 17.0.1.0.0/
        ├── pre-migration.py
        ├── post-migration.py
        └── noupdate_changes.xml

Pre-migration example:

from openupgradelib import openupgrade

@openupgrade.migrate()
def migrate(env, version):
    # Rename fields before module loads
    openupgrade.rename_fields(env, [
        ('sale.order', 'sale_order', 'old_field', 'new_field'),
    ])
    
    # Rename models
    openupgrade.rename_models(env.cr, [
        ('old.model', 'new.model'),
    ])

Post-migration example:

from openupgradelib import openupgrade

@openupgrade.migrate()
def migrate(env, version):
    # Map old values to new
    openupgrade.map_values(
        env.cr,
        openupgrade.get_legacy_name('state'),
        'state',
        [('draft', 'pending'), ('confirm', 'confirmed')],
        table='sale_order',
    )
    
    # Recompute fields
    env['sale.order'].search([])._compute_total()

Common migration tasks:

• Rename fields: openupgrade.rename_fields()
• Rename models: openupgrade.rename_models()
• Rename tables: openupgrade.rename_tables()
• Map values: openupgrade.map_values()
• Delete obsolete data: openupgrade.delete_records_safely_by_xml_id()

5. Module Extension

Extend core Odoo modules following OCA patterns.

Inherit existing model:

from odoo import fields, models

class ResPartner(models.Model):
    _inherit = 'res.partner'
    
    custom_field = fields.Char(string="Custom Info")

Extend existing view:

<record id="res_partner_view_form" model="ir.ui.view">
    <field name="model">res.partner</field>
    <field name="inherit_id" ref="base.view_partner_form"/>
    <field name="arch" type="xml">
        <xpath expr="//field[@name='email']" position="after">
            <field name="custom_field"/>
        </xpath>
    </field>
</record>

Module dependencies:

• Always declare dependencies in __manifest__.py
• Use depends key for Odoo core/OCA modules
• Use external_dependencies for Python packages
• Document installation requirements in README

6. Validation and Quality

Validate module structure:

python scripts/validate_module.py /path/to/module

What is checked:

• Required files presence (__init__.py, __manifest__.py)
• Manifest completeness (required keys)
• OCA author attribution
• License compliance (AGPL-3 or LGPL-3)
• Version format (x.y.z.w.v)
• File naming conventions
• Directory structure

Code quality tools:

# Install pre-commit for OCA checks
pip install pre-commit
pre-commit install

# Run checks
pre-commit run --all-files

# Run specific checks
flake8 module_name/
pylint --load-plugins=pylint_odoo module_name/

Workflow Decision Tree

"I need to create a new Odoo module" → Use scripts/init_oca_module.py to generate OCA-compliant structure → Edit __manifest__.py with module details → Create models in models/ directory → Create views in views/ directory → Add security rules in security/ → Update readme/ documentation → Run validation: scripts/validate_module.py

"I need to migrate a module to a new Odoo version" → Check OpenUpgrade for breaking changes → Create migration folder: migrations/<new_version>/ → Write pre-migration script for schema changes → Write post-migration script for data transformation → Test on copy of production database → Reference openupgrade_migration.md

"I need to extend a core Odoo module" → Create new module with core module in depends → Use _inherit to extend models → Use inherit_id to extend views → Follow OCA naming: <core_module>_<feature> → Keep changes minimal and focused

"I'm not sure if my module follows OCA conventions" → Run scripts/validate_module.py → Check oca_conventions.md → Review manifest.py for required keys → Verify file naming and structure → Ensure OCA author attribution

Resources

scripts/

• init_oca_module.py: Create new Odoo module with OCA-compliant structure
• validate_module.py: Validate module against OCA conventions

references/

• oca_conventions.md: Complete OCA coding standards and module structure guidelines
• openupgrade_migration.md: OpenUpgrade migration patterns and best practices

assets/

• module_template/: Official OCA module template with complete directory structure

Best Practices

Module Development

• Start with OCA template: scripts/init_oca_module.py
• Follow naming conventions strictly
• One file per model
• Keep models, views, and data separate
• Use meaningful xmlids following OCA patterns
• Include comprehensive tests
• Document in readme/ folder

Code Quality

• Follow PEP8 for Python code
• Use 4-space indentation in XML
• No SQL injection vulnerabilities
• Never bypass ORM without justification
• Never commit transactions manually
• Use _logger.debug() for import errors
• Handle external dependencies properly

Git Commits

Format: [TAG] module_name: short summary

Common tags:

• [ADD] - New feature/module
• [FIX] - Bug fix
• [REF] - Refactoring
• [IMP] - Improvement
• [MIG] - Migration
• [REM] - Removal

Migration Strategy

1. Study OpenUpgrade analysis for target version
2. Check for breaking changes in core modules
3. Test on database copy first
4. Write pre-migration for schema changes
5. Write post-migration for data transformation
6. Document breaking changes in README
7. Update version following semantic versioning

Common Patterns

Pattern: Add computed field with dependencies

total = fields.Float(compute='_compute_total', store=True)

@api.depends('line_ids.amount')
def _compute_total(self):
    for record in self:
        record.total = sum(record.line_ids.mapped('amount'))

Pattern: Extend view safely

<xpath expr="//field[@name='partner_id']" position="after">
    <field name="custom_field"/>
</xpath>

Pattern: Add security group

<record id="group_custom" model="res.groups">
    <field name="name">Custom Access</field>
    <field name="category_id" ref="base.module_category_sales"/>
</record>

Pattern: Migration with value mapping

openupgrade.map_values(
    env.cr,
    openupgrade.get_legacy_name('old_field'),
    'new_field',
    [('old_value', 'new_value')],
    table='model_table',
)

Troubleshooting

Module not appearing in Apps

• Check 'installable': True in manifest.py
• Verify init.py imports
• Run: odoo-bin -u module_name -d database

Import errors

• Add try-except for external dependencies
• Document installation in readme/INSTALL.rst
• Add to requirements.txt for Python packages

Migration fails

• Check pre-migration runs before module load
• Verify table/column names with \d table in psql
• Use openupgrade.logged_query() for debugging
• Test on copy database first

Tests failing

• Use tagged('post_install', '-at_install')
• Test with minimal user permissions using @users()
• Avoid dynamic dates, use freezegun
• Mock external services

Quick Reference

Create module:

python scripts/init_oca_module.py my_module --version 17.0

Validate module:

python scripts/validate_module.py path/to/module

Check conventions: See oca_conventions.md

Migration guide: See openupgrade_migration.md

Module template: Copy from assets/module_template/