The previous article introduced how to get started with OCA work at an overview level.
This time we set out the concrete flow for submitting a PR (pull request) to an OCA GitHub repository.
OCA Contributors Guidelines & Community Handbook is the source for this article, which covers:
- the basic rules for creating a PR
- CI checks
- handling reviews
- the points beginners tend to trip over
Each of them is set out from a practical standpoint.
Use this article as a reference if you are a developer reasonably at home with Git, Python and Odoo's technical documentation, and you are taking on a first OCA module improvement, version upgrade or new module.
The section on where newcomers get confused in particular is drawn from what comes up again and again in real reviews.
The full workflow up to a merge
The OCA defines the flow up to a PR being merged clearly.
Start by taking in the whole picture.
Step 1: Preparation
- CLA (Contributor License Agreement) — signed once, the first time only
- In your development environment, install pre-commit
- Check the existing issues and PRs (to avoid duplication)
- Choose the repository, if you are adding a new module
Which repository to open a PR against is a decision you make by checking that repository's README
Step 2: Creating the PR
■ Basic rules
- Target branch: 16.0 or 18.0 (note that you do not open a PR against main / master.)
- Commit message: the form ”[TAG] module_name: description of the change”.
Example tags: [FIX], [IMP], [ADD], [MIG]. Refer to the conventions for the full list.
[FIX] module_name: what was fixed
[ADD] module_name: the new feature- PR title: include the version tag at the front
[18.0][FIX] module_name: what was fixed- As a rule, "one PR = one commit" is recommended.
Except when handling several issues or doing migration work, squash as needed and bring it down to a single commit.
Step 3: CI (continuous integration) checks
Creating a PR triggers the automated checks (CI).
- pre-commit (a check on how the code is written): checks formatting and linting. Run it locally before you push
- Test: GitHub Actions runs the module's tests.
- Runboat: provides a live test instance for functional testing.
- Codecov: a report on test coverage (for information)
👉 If a CI check fails, fix it, push again and the checks re-run.
Step 4: Handling reviews
Handling reviews is the part of OCA work that matters most.
- Responding to review comments and explaining yourself carefully matters
- Turn fixes around quickly
- Several rounds back and forth is normal
👉 A careful, positive response is what gets a PR accepted.
The OCA how-to guides are here
■ Conditions for a merge
- Three approvals (within five days), or two (after five days)
- One PSC member's approval is required
Once approved, a PSC member runs " /ocabot merge " to merge it.
Where newcomers tend to get confused
■ Reviews do not arrive straight away
- The OCA is volunteer-based, so reviews can take time.
👉 What to do: take part in reviewing other people's PRs
■ Being treated as Stale
- With no activity for 120 days, it closes automatically
👉 A comment brings it back
■ Feedback, review comments and requests for changes are normal
- Code style
- Missing tests
- Odoo design rules
👉 You may get comments on code style (pre-commit, ruff, prettier and so on), test coverage, and Odoo patterns. This process is not criticism; it is joint work towards better quality.
Common beginner mistakes
This part matters a great deal.
❌ Submitting translations as a PR
→ Use Weblate for that.
❌ A PR covering several topics
→ Keep each pull request focused on a single issue or feature. Where a change touches several topics or several modules, split it into a separate pull request for each.
❌ Submitting AI-generated code as it comes
→ Do not submit AI-generated code as it comes; understand and go over it properly first.
❌ Not having run pre-commit
→ Check locally beforehand.
❌ A migration PR with no history
When migrating a module to a new version, preserve the Git history and follow the official migration guide as written.
❌ A PR title or commit message in the wrong form
→ Follow the conventions as given.
Resources and help
For more detail on the OCA, see the following.
■ Community
■ Development and technical information
- Odoo official documentation: for models, views, tests and the Odoo framework, the official Odoo reference
- Maintainer tools wiki: for repository setup, coding conventions and migration, the OCA's guides and conventions
- CI (continuous integration): the OCA CI workflow runs tests automatically against every PR. Runboat provides a test instance linked from a pull request's GitHub checks.
■ OCA official information
- OCA GitHub: github.com/OCA lists every repository.
- OCA website: odoo-community.org — general information about the OCA, including events, working groups and branding material.
- OCA guidelines: the OCA guidelines for taking part in OCA work are here, and worth reading first.
- Translation: goes through Weblate. See How Odoo and OCA Japanese translation works on Weblate for the working procedure. Information on the translation procedure for the OCA's own site is here as well.
In closing
Contributing to the OCA is not merely open-source activity.
It is continuous community work aimed at making Odoo easier for companies all over the world to use.
At first the GitHub practices, the coding conventions, dealing with CI and the review culture may all be confusing.
But by taking part continuously you get:
- better Odoo development skills
- improved code quality
- experience of working as a team
- a point of contact with a global community
Those are substantial benefits.
And rather than holding OCA work apart as "special open-source activity", building it into your day-to-day development flow and internal rules makes it something you can draw on naturally in real work.
To begin with:
- start with a small improvement PR
- keep taking part
- get involved in reviewing others' work too
Keeping those three in mind is probably a good way to go about it.
At Quartile we support Odoo implementations in line with the OCA guidelines, and we bring what we learn from community work into our projects day to day.
OCA work explained, in practice: writing a GitHub pull request, handling review, and getting it merged