ERP Customization Documentation Standard

Odoo owns the platform, the build pipeline and the version upgrades. Every push produces a new build, and a version bump can change core behaviour underneath code nobody touched.

That moves where the risk lives. The failures that cost money are not the ones a linter catches — they are assumptions about core that were true once, were never written down, and quietly stopped being true. Two of them, both real, both from a single Odoo 19 → 20 port:

Neither is visible by reading our own code. Both are seconds away in core, or in a schema diff. This standard exists to make that reading mandatory, and to make its result durable.

Two definitions do most of the work in what follows.

A customization is not done when it works. It is done when the next engineer can tell why it is shaped that way without asking the author.

Never document Odoo behaviour from memory, and never accept a claim that carries no evidence.

Recalled API knowledge is unreliable across versions, and confidently wrong documentation is worse than none — because it gets trusted. Every claim about core behaviour must cite one of three things:

Keep the core source for the target version readable locally, and read it before writing about it:

grep -n "state = fields.Selection" -A6 \
  <odoo>/addons/hr_attendance/models/hr_attendance.py

On Odoo SH, schema evidence comes from a staging build, which runs on a neutralized copy of the production database. Comparing one table across a pre-upgrade and a post-upgrade build settles most “is this field still stored?” questions outright:

SELECT column_name FROM information_schema.columns
 WHERE table_name = '<table>' ORDER BY 1;

A column present before the upgrade and absent after it is a real finding, whatever the Python says.

Label confidence

Every finding in a review or a migration note carries one of two labels:

A claim about core with no version attached is not a claim, it is folklore.

Write “in 20.0, hr.version carries a unique index on (employee_id, date_version) WHERE active” — not “contracts must have unique dates”. The first survives an upgrade by being checkable. The second does not.

This bites hardest on access control, because access mistakes fail silently and in the permissive direction. When changing access rules, write down the answers to:

A comment describing behaviour the code no longer has is a defect, and will be reported as one.

When a guard, a branch or an override is removed, its comment goes with it. Two failure modes, both seen in review:

• A write() override whose comment said the method “checks” a state it no longer checked.
• A test asserting an error the code had stopped raising, kept alive by a comment explaining the old behaviour.

Migration notes are the long form of the same duty. For each version bump, record what core renamed or moved, what we changed in response, what we deliberately did not change, and what still needs a human decision.

Odoo SH gives three branch stages. The documentation obligation differs at each.

Because a staging build carries real production data shape, it is the last honest checkpoint. A claim that was only ever tested against a demo database stays labelled SUSPECTED until it has been re-checked on staging.

A review that exists only in a chat window is invisible to the next engineer, to the next session, and to CI — and the PR merges looking unreviewed, because as far as anything can tell, it is.

1. Post every review as its own PR comment. Always, including a pass. Not folded into the PR description; not reported only in chat.
2. Pin it to the commit. A review is of a commit, not of a pull request. Record the head SHA and put it in the receipt.
3. End the body with a machine-readable receipt line, which renders invisibly and costs the reader nothing.
4. Write the body to a file and pass --body-file. A review body is full of backticks; inlined in a double-quoted shell argument it goes through command substitution.

<!-- baseup-review kind=<kind> sha=<full-40-char-headRefOid> verdict=PASS|BLOCK -->

A rule that depends on remembering to follow it is a suggestion. The review in §8 is enforced before the push leaves the machine, not after it lands.

lefthook.yml binds a pre-push hook that runs the review over the outgoing diff and exits non-zero on a blocking finding, refusing the push. Install it once per clone — without this, nothing gates anything:

brew install lefthook && lefthook install

The review runs on the Claude Code CLI already signed in on the engineer's machine. There is no API key to provision and no shared credential: if you can run claude, the gate works. The hook resolves the binary itself rather than trusting PATH, because git hooks inherit a stripped one and the IDE extensions ship it at a version-stamped path.

What blocks, and what does not

Failing closed

If the review cannot produce a readable verdict, the gate blocks. A gate that passes when it cannot tell is not a gate. When the reviewer itself cannot run — no CLI on the machine, not signed in — it records SKIPPED and allows the push, because a missing tool is not evidence of a defect.

A non-zero exit from the agent counts as “no review happened” only when the output also carries no verdict. If the agent reached a verdict and then exited non-zero, that verdict still stands — otherwise a stray exit code would silently turn a BLOCK into a pass.

The two bypasses are not equivalent

SKIP_AI_REVIEW=1 git push        # recorded
git push --no-verify             # NOT recorded

The bypass exists so a misfiring gate never blocks an emergency fix. SKIP_AI_REVIEW=1 runs the hook, which writes a BYPASS receipt and lets the push through — the skip stays visible afterwards instead of being indistinguishable from a passing one.

A customization may be promoted to production when all of the following hold.

Each of these has cost someone a production incident or a wasted review cycle.

What the standard looks like applied to one line of a diff.

The whole standard is an attempt to make that four-row table cheap enough that people actually fill it in.