Quick Start Guide

---

What Is the OCA Addon Repo Template?

First, the OCA Addon Repo Template acts as a starter kit, or scaffold, for any new OCA module repository. Next, it defines a standard folder layout, configuration files, and pre-commit hooks. Then, it integrates code linters, formatters, and security checks automatically. As a result, you and your team maintain consistency across dozens of addons. Finally, you avoid repetitive setup, and you can focus on writing business logic instead of boilerplate.

This template leverages Copier to generate files from a remote repository. Moreover, it uses pre-commit to run tasks like flake8, black, and isort before each commit. Consequently, your code stays clean and meets OCA standards.

---

Prerequisites for Using the Template

Before you use the OCA Addon Repo Template, ensure you have:

1. Python 3.7 or higher
2. pipx for installing and isolating command-line tools
3. Git for version control
4. Access to the internet to clone the template repository
5. Basic knowledge of terminal commands and Python packaging

You can install pipx via Python’s package installer if you don’t have it yet:

python3 -m pip install --user pipx
python3 -m pipx ensurepath

---

Installing Required Tools

You perform two main installations: pipx itself and the two tools—Copier and pre-commit—that the template depends on.

Installing pipx

1. You install pipx with pip: python3 -m pip install --user pipx
2. You add pipx to your PATH: python3 -m pipx ensurepath
3. You restart your terminal so pipx commands become available.

Installing Copier & pre-commit

After pipx is ready, you install Copier and pre-commit globally but inside isolated environments. This approach prevents conflicts with your system Python packages.

# Install Copier for templating
pipx install copier

# Install pre-commit for Git hooks
pipx install pre-commit

Tip: If you ever upgrade Python, you may need to reinstall pipx or rerun pipx ensurepath.

---

Bootstrapping a New OCA Addon Repository

Now that your tools are in place, you clone the OCA Addon Repo Template and answer a few questions to generate your own repo.

Running the Copier Scaffold

First, you choose a directory name for your new repo, for example my-oca-addon. Next, you run the Copier command as follows:

copier copy --UNSAFE https://github.com/OCA/oca-addons-repo-template.git my-oca-addon

• --UNSAFE allows Copier to overwrite files if you rerun the command.
• You replace my-oca-addon with your preferred folder name.
• Copier prompts you for project metadata, like author name, module description, and OCA team.

During this step, answer prompts interactively. For example:

Project human name: My OCA Addon
Module name: my_oca_addon
Download URL: https://github.com/my-org/my_oca_addon
Version: 18.0.1.0.0
Maintainer email: dev@mycompany.com

Copier generates a fully functional Git repository with:

• addons/ folder for your Odoo modules
• docs/ folder with guidelines
• Configuration files (.pre-commit-config.yaml, setup.cfg, README.rst)
• Sample tests and CI configuration

Initializing Git and pre-commit Hooks

Then, you move into the newly created directory and set up Git and pre-commit hooks:

cd my-oca-addon
git init
git add .
pre-commit install
pre-commit run -a
git commit -m "Initial commit: Bootstrap add-on repository from OCA template"

1. git init creates a new Git repo.
2. git add . stages all generated files.
3. pre-commit install adds hooks to the .git/hooks folder.
4. pre-commit run -a formats and lints all files immediately.
5. git commit captures the cleaned, uniform codebase.

From now on, every time you run git commit, pre-commit runs checks automatically. As a result, you catch errors early and maintain code quality.

---

Developing Your First Addon

With the repository scaffolded, you begin developing your actual OCA addon modules inside the addons/ folder.

Creating the Module Structure

Inside addons/, you create a new subfolder that matches the module name:

cd addons
mkdir my_oca_addon
cd my_oca_addon

Then, you add these essential files and folders:

• __init__.py to mark the folder as a package
• __manifest__.py to define module metadata
• models/ folder for Python model classes
• views/ folder for XML views
• data/ folder for demo or test data
• tests/ folder for automated tests

Your structure should look like:

addons/
└── my_oca_addon/
    ├── __init__.py
    ├── __manifest__.py
    ├── models/
    │   └── __init__.py
    ├── views/
    ├── data/
    └── tests/

Writing the Manifest File

Next, you open __manifest__.py and fill in metadata:

{
    'name': 'My OCA Addon',
    'version': '18.0.1.0.0',
    'category': 'Tools',
    'summary': 'Adds a custom feature X',
    'description': """
This module extends Odoo 18 to support advanced feature X.
It follows OCA standards and uses the template config.
""",
    'author': 'Your Name',
    'website': 'https://github.com/my-org/my_oca_addon',
    'license': 'AGPL-3',
    'depends': ['base'],
    'data': [
        'views/my_feature_view.xml',
    ],
    'installable': True,
    'application': False,
}

• You set name, version, and license.
• You reference XML files under the data section.
• You ensure installable stays True.

Adding Models and Views

Then, you create a basic model in models/my_feature.py:

from odoo import models, fields

class MyFeature(models.Model):
    _name = 'my.feature'
    _description = 'My Custom Feature'

    name = fields.Char(string='Name', required=True)
    active = fields.Boolean(string='Active', default=True)

Next, you load this model in models/__init__.py:

from . import my_feature

Finally, you add a simple form view in views/my_feature_view.xml:

<odoo>
  <record id="view_my_feature_form" model="ir.ui.view">
    <field name="name">my.feature.form</field>
    <field name="model">my.feature</field>
    <field name="arch" type="xml">
      <form string="My Feature">
        <sheet>
          <group>
            <field name="name"/>
            <field name="active"/>
          </group>
        </sheet>
      </form>
    </field>
  </record>
</odoo>

After you add code and XML, you run pre-commit again:

pre-commit run -a
git add .
git commit -m "Add MyFeature model and view"

---

Updating Your Repository from the Template

Over time, the OCA Addon Repo Template itself improves. You can pull those updates into your repo without losing your custom code.

Running Copier Update

First, you enter your repo root and run:

cd my-oca-addon
copier update --UNSAFE

• Copier fetches updates from the original template repo.
• Copier merges new files and highlights conflicts in your custom files.

Committing Template Changes

Then, you apply pre-commit formatting and commit:

pre-commit run
git commit -m "Update repository structure from OCA template"

If the pre-commit config changed, you run a full format:

pre-commit run -a
git commit -m "Reformat after template update"

Consequently, your repo stays in sync with the latest best practices.

---

Integrating Continuous Integration (CI)

Next, you integrate a CI pipeline—such as GitHub Actions—to run pre-commit on every push or pull request.

Create .github/workflows/ci.yml:

name: CI

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  pre-commit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.9'
      - name: Install pipx
        run: python3 -m pip install --user pipx && python3 -m pipx ensurepath
      - name: Install Tools
        run: |
          pipx install copier || true
          pipx install pre-commit || true
      - name: Run pre-commit
        run: pre-commit run --all-files

This workflow ensures that every commit meets style, lint, and security standards automatically.

---

Best Practices for OCA Addon Repo Template

• Answer Copier Prompts Thoughtfully: Provide accurate metadata to avoid changing it later.
• Review Template Updates: Always inspect diffs after copier update to avoid unintentional overrides.
• Limit --UNSAFE Usage: Use it only when necessary, and understand its implications.
• Lock Pre-commit Versions: Pin hook versions in .pre-commit-config.yaml to avoid sudden changes.
• Use Automated Tests: Write unit tests under tests/ to catch regressions early.
• Document Customizations: Update README.rst with usage notes for your addon.
• Maintain Branch Hygiene: Merge template updates into a dedicated branch before merging to main.

---

Troubleshooting Common Issues

1. Copier Authentication Errors
   • Use SSH URLs or provide GITHUB_TOKEN if you hit rate limits.
2. Pre-commit Hook Failures
   • Resolve formatting errors locally before pushing.
3. Missing Dependencies
   • Check requirements.txt and run pip install -r requirements.txt.
4. Merge Conflicts After Update
   • Resolve conflicts manually, then rerun pre-commit run -a.
5. Template Version Drift
   • Tag your initial commit and compare template versions before updating.

---

Conclusion and Next Steps

You now master the OCA Addon Repo Template. You learned to:

• Install pipx, Copier, and pre-commit.
• Bootstrap a fresh OCA addon repo.
• Add your first module code and views.
• Update your repo when the template evolves.
• Integrate CI to enforce quality.

Next, you should:

1. Explore OCA Guidelines at the OCA website.
2. Contribute Back by sending pull requests to the template repo.
3. Automate Releases by adding GitHub Actions for PyPI packaging.

By following this guide, you accelerate your Odoo addon development and maintain high code quality across all your projects. Happy coding!