Contributing a PR to an OCA repo
Load whichever odoo-module-* skill matches the actual change
(odoo-module-create for a new module, odoo-module-migrate for a version
port, etc.) — this skill covers the submission process, not the code
content.
1. Fork & branch
Work inside your project's own checkout of the repo (e.g.
odoo/custom/src/<repo> in Doodba-based projects, added via repos.yaml)
rather than a separate unrelated clone, so your project's own tooling
(install, addon-path resolution) actually sees the module you're changing.
- Fork the upstream repo on GitHub if you haven't already.
- Add your fork as a remote:
git remote add <your_org> https://github.com/<your_org>/<repo>.git.
- Branch from the target version, named after the change:
- Migration:
<version>.0-mig-<module> (e.g. 18.0-mig-partner_statement).
- Everything else:
<version>.0-<tag>-<module> using the tag from
reference/commit-conventions.md in odoo-module-review
(18.0-fix-stock_picking_batch, 18.0-add-sale_order_type).
2. Shape the commits
Follow reference/commit-conventions.md (in the odoo-module-review skill)
for the tag taxonomy. Concretely:
- One commit per logical step, not one giant commit — reviewers read history,
not just the final diff.
- If pre-commit auto-formats your first commit's code, that's its own
[IMP] <module>: pre-commit auto fixes commit, separate from the functional
change — same split odoo-module-migrate documents for migrations.
- Run your project's lint suite and the module's tests before pushing
(e.g.
invoke lint / invoke test -m <module_name> in Doodba-based
projects) — don't rely on CI to catch what you could catch locally in
seconds.
3. Open the PR
- Title:
[<version>.0][<TAG>] <module>: <short description> (see
odoo-module-review's reference file).
- Description should cover, briefly:
- What changed and why (link the issue it closes, if any:
Closes #123).
- For a UI change: a before/after screenshot — reviewers on OCA PRs
routinely ask for one if it's missing.
- For a migration: which version it migrates from, and anything from the
target version's breaking-change reference that needed a non-obvious
workaround.
- Push to your fork's branch, open the PR against the upstream repo's
target version branch (not
main/master — OCA repos branch per Odoo
version).
4. CI/bot checks — what they mean and how to fix them
| Check |
What it verifies |
Typical fix |
pre-commit.ci / GitHub Actions lint job |
The project's pre-commit suite (pylint-odoo, oca-checks-odoo-module, oca-checks-po, ruff/black, prettier) |
Run the lint suite locally and push the fix — don't try to guess the failure from the CI log alone if you can reproduce it locally. |
| Test job |
The project's test suite, run in CI across supported DB/Odoo combinations |
Reproduce locally first, the way your project runs tests (e.g. invoke test -m <module_name> in Doodba-based projects). |
| Runboat |
Spins up a live preview instance of the PR |
Use it to manually click through the change before asking for review — catches things tests don't. |
| Weblate bot comment |
Notes the module is now tracked for community translation |
Informational — no action needed unless it flags a .po conflict. |
| Codecov |
Coverage delta from the PR |
A red delta on new code usually means the odoo-module-test checklist wasn't fully applied — add the missing test, don't just accept the drop. |
| Bot asking for a rebase/merge conflict resolution |
Base branch moved since the PR was opened |
git fetch upstream <version> && git rebase upstream/<version>, force-push the same branch — don't open a new PR. |
5. Responding to review feedback
- Push additional commits (or amend + force-push) to the same branch — the
PR updates in place; don't close and reopen.
- If a reviewer asks for a change already covered by one of the
odoo-module-* skills' checklists, fix it per that skill rather than
improvising a one-off solution — keeps the module consistent with the rest
of the repo.
- Once approved, OCA maintainer bots typically handle the actual merge
(squash or merge-commit per repo convention) — you generally don't need to
merge it yourself.
1---2name: odoo-pr-contribution3description: Prepare and submit a mergeable pull request to an OCA (or OCA-style) repo: fork/branch setup, commit shaping, PR description, and responding to CI/bot checks. Use when asked to open, submit, or prepare a PR for an Odoo module change, or to fix a failing PR check (runboat/weblate/pre-commit.ci/codecov).4---56# Contributing a PR to an OCA repo78Load whichever `odoo-module-*` skill matches the actual change9(`odoo-module-create` for a new module, `odoo-module-migrate` for a version10port, etc.) — this skill covers the *submission process*, not the code11content.1213## 1. Fork & branch1415Work inside your project's own checkout of the repo (e.g.16`odoo/custom/src/<repo>` in Doodba-based projects, added via `repos.yaml`)17rather than a separate unrelated clone, so your project's own tooling18(install, addon-path resolution) actually sees the module you're changing.19201. Fork the upstream repo on GitHub if you haven't already.212. Add your fork as a remote: `git remote add <your_org> https://github.com/<your_org>/<repo>.git`.223. Branch from the target version, named after the change:23 - Migration: `<version>.0-mig-<module>` (e.g. `18.0-mig-partner_statement`).24 - Everything else: `<version>.0-<tag>-<module>` using the tag from25 `reference/commit-conventions.md` in `odoo-module-review`26 (`18.0-fix-stock_picking_batch`, `18.0-add-sale_order_type`).2728## 2. Shape the commits2930Follow `reference/commit-conventions.md` (in the `odoo-module-review` skill)31for the tag taxonomy. Concretely:3233- One commit per logical step, not one giant commit — reviewers read history,34 not just the final diff.35- If pre-commit auto-formats your first commit's code, that's its own36 `[IMP] <module>: pre-commit auto fixes` commit, separate from the functional37 change — same split `odoo-module-migrate` documents for migrations.38- Run your project's lint suite and the module's tests **before** pushing39 (e.g. `invoke lint` / `invoke test -m <module_name>` in Doodba-based40 projects) — don't rely on CI to catch what you could catch locally in41 seconds.4243## 3. Open the PR4445- Title: `[<version>.0][<TAG>] <module>: <short description>` (see46 `odoo-module-review`'s reference file).47- Description should cover, briefly:48 - What changed and why (link the issue it closes, if any: `Closes #123`).49 - For a UI change: a before/after screenshot — reviewers on OCA PRs50 routinely ask for one if it's missing.51 - For a migration: which version it migrates from, and anything from the52 target version's breaking-change reference that needed a non-obvious53 workaround.54- Push to **your fork's branch**, open the PR against the upstream repo's55 target version branch (not `main`/`master` — OCA repos branch per Odoo56 version).5758## 4. CI/bot checks — what they mean and how to fix them5960| Check | What it verifies | Typical fix |61|---|---|---|62| `pre-commit.ci` / GitHub Actions lint job | The project's pre-commit suite (pylint-odoo, oca-checks-odoo-module, oca-checks-po, ruff/black, prettier) | Run the lint suite locally and push the fix — don't try to guess the failure from the CI log alone if you can reproduce it locally. |63| Test job | The project's test suite, run in CI across supported DB/Odoo combinations | Reproduce locally first, the way your project runs tests (e.g. `invoke test -m <module_name>` in Doodba-based projects). |64| **Runboat** | Spins up a live preview instance of the PR | Use it to manually click through the change before asking for review — catches things tests don't. |65| **Weblate** bot comment | Notes the module is now tracked for community translation | Informational — no action needed unless it flags a `.po` conflict. |66| **Codecov** | Coverage delta from the PR | A red delta on new code usually means the `odoo-module-test` checklist wasn't fully applied — add the missing test, don't just accept the drop. |67| Bot asking for a rebase/merge conflict resolution | Base branch moved since the PR was opened | `git fetch upstream <version> && git rebase upstream/<version>`, force-push the **same** branch — don't open a new PR. |6869## 5. Responding to review feedback7071- Push additional commits (or amend + force-push) to the **same branch** — the72 PR updates in place; don't close and reopen.73- If a reviewer asks for a change already covered by one of the74 `odoo-module-*` skills' checklists, fix it per that skill rather than75 improvising a one-off solution — keeps the module consistent with the rest76 of the repo.77- Once approved, OCA maintainer bots typically handle the actual merge78 (squash or merge-commit per repo convention) — you generally don't need to79 merge it yourself.
CristianoMafraJunior