# Frequently Asked Questions

## Multi-release Odoo addons? Are you crazy?

Developing multi-release Odoo addons
[isn’t officially supported](https://github.com/odoo/odoo/pull/25371#issuecomment-401418161).
That makes sense for Odoo SA — each release is a full product. Need new features? Just
upgrade. Their strict no-database-changes rule, auto-forward ports, and 3-year support
policy keep things manageable. When a new Odoo ships, their whole product upgrades. This
works great _for upstream_.

For _downstream_, multi-release addons also bring challenges:

-   Code decay, messy shared code, and tech debt
-   Can’t always use the newest ORM features in older versions

So, **yeah, maybe we’re crazy**. But if you’re crazy like us, here’s what you now can
do:

-   Develop addons that are production-ready the day a new Odoo is released
-   Maintain your module like any normal Python project — treat Odoo as just another
    dependency
-   Build your own product on top of Odoo
-   Support older releases with way less work
-   Never migrate modules again — just add or drop Odoo release support

Crazy too? Welcome aboard!

## Installation

### How do I install polytropos?

From PyPI (recommended):

```bash
pip install polytropos
```

Or with uv:

```bash
uv pip install polytropos
```

You can also run it without installing it:

```bash
uvx polytropos --help
```

### Can I install from GitLab Packages?

Yes! The package is public, so no authentication required. GitLab Packages mirrors PyPI
releases:

```bash
pip install polytropos --index-url https://gitlab.com/api/v4/projects/moduon%2Fpolytropos/packages/pypi/simple
```

Or with uv, add this to your `pyproject.toml`:

```toml title="pyproject.toml"
[[tool.uv.pip]]
index-url = "https://gitlab.com/api/v4/projects/moduon%2Fpolytropos/packages/pypi/simple"
```

### Do I need uv?

uv is recommended for best experience, but not required. You can also use pip.

### Can't I just use Nix?

Of course!

```shell
nix run github:moduon/polytropos
```

## Usage

### How do I create a new module?

```bash
uvx polytropos init my_module
```

This creates a `pyproject.toml` with sensible defaults.

### How do I build a wheel for a specific Odoo release?

```bash
uv build --wheel --config-setting odoo_release=17.0
```

The wheel will include the Odoo release in its version (e.g.,
`odoo-addon-my-module-17.0.1.0.0-py3-none-any.whl`).

### How do I develop in editable mode?

Use uv's built-in editable support:

```bash
cd /path/to/your/integration/env
uv add --editable ../my_module
```

Then set the Odoo release:

```bash
uv sync --config-setting odoo_release=17.0
```

Or add it in your integration environment's `pyproject.toml`:

```toml title="pyproject.toml"
[tool.uv.config-settings]
odoo_release = "17.0"
```

## Configuration

### What's the difference between `releases` and `default_odoo_release`?

-   `default_odoo_release`: Fallback odoo release to use when building/installing
-   `releases`: Which Odoo releases this manifest section applies to

!!! example

    ```toml title="pyproject.toml"
    [tool.polytropos]
    default_odoo_release = "18.0"

    [[tool.polytropos.manifest]]
    releases = ">=18"
    # This applies to all Odoo 18+

    [[tool.polytropos.manifest]]
    releases = ">=17,<18"
    # This applies only to Odoo 17.x
    ```

Polytropos uses [PEP 440](https://peps.python.org/pep-0440/) version specifiers.

### How does version building work?

Polytropos combines your module version with the Odoo release:

-   Module version: `1.2.3` (from `pyproject.toml`)
-   Odoo release: `17.0`
-   Full version: `17.0.1.2.3`

This follows Odoo's versioning convention where the Odoo release comes first.

## Documentation

### How to read a specific version of the docs?

!!! warning

    Public docs are built on last commit always, so they might not exactly reflect the
    last published stable version.

To get a specific version of the docs, run:

```shell
git_ref=v3.1.0 # Change for the docs you want to see
nix --extra-experimental-features 'nix-command flakes' --accept-flake-config \
    "gitlab:moduon/polytropos/$git_ref#livedocs"
```

It will run a local docs server built at that specific version.

## Architecture

Polytropos delegates the actual build process to
[whool](https://github.com/sbidoul/whool):

1. **Polytropos** reads `pyproject.toml` and generates a version-specific
   `__manifest__.py`
2. **Whool** builds the wheel from the generated manifest

This separation of concerns allows Polytropos to focus on multi-version manifest
generation while leveraging whool's well-tested build backend.

### Why the addon version must have 3 or more components?

The version format `A.B.X.Y.Z` (5 components) is required so that manifestoo-core and
Odoo are able to distinguish between the Odoo release and the addon version. The format
breaks down as:

-   `A.B` - Odoo release, always prepended by Polytropos (e.g., `17.0`)
-   `X.Y.Z` - Module version (e.g., `1.2.3`)

Your module version must have at least 3 components (X.Y.Z). If your module version has
fewer than 3 components (e.g., `1.0`), polytropos will raise an error.

## Troubleshooting

### `uv sync` fails with "missing build dependencies"

Make sure your integration environment's `pyproject.toml` includes polytropos as a build
dependency:

```toml title="pyproject.toml"
[build-system]
requires = ["polytropos[build]"]
build-backend = "polytropos.build"
```

### The built wheel has wrong Odoo release

Make sure you're passing the correct `odoo_release` config setting to uv/pip when
building.

### `uv build` fails because sdist and wheel have different versions

Running `uv build` on an addon will fail with:

```shell
uv build --no-build-isolation
Building source distribution...
Building wheel from source distribution...
  × Failed to build
  │ `polytropos/examples/conditional_assets`
  ╰─▶ The source distribution declares version 1.0.0, but the wheel declares version 19.0.1.0.0
```

This is [on purpose](build-types.md#version).

To workaround the problem, build in 2 separate steps:

```shell
uv build --sdist
uv build --wheel
```
