Code Review

Who checks what, and what a pull request needs before it is approved.

Three layers

Layer	Owner	Covers
Mechanical	CI	formatting, lint, unit tests, secret scan, DCO, Conventional Commits, pinned actions, docs build
Structural	Human reviewer	correctness, architecture fit, security, failure modes, test value
Narrative	Author, read by the reviewer	why the change exists, what it affects, how it was verified

Reviewers avoid repeating findings already reported by CI. If a reviewer finds a problem that CI missed, they should report it and suggest an automated check where practical.

Pull request size

• Aim for under 500 changed lines of hand-written code.
• Keep refactors in their own pull request, separate from behaviour changes.
• Generated content does not count — lockfiles, helm-docs chart READMEs, snapshots. Say in the description which part of the diff is generated.
• If a change cannot be split, say why in the description and name the order in which commits should be read.

Size is guidance, not a gate. No check blocks a pull request for being large.

Automatic size labels

Open PRs, including forks and drafts, receive an advisory size/* label when a complete file count is available.

Label	XS	S	M	L	XL	XXL
Changed lines	0–9	10–29	30–99	100–499	500–999	1000+

• Count additions plus deletions, excluding generated files. Generated-only PRs are size/XS.
• Label definitions and generated-file globs.
• Workflow operation, backfill, and API limitations.

What a reviewer checks

Structural

• Does the change do what the description says, and only that?
• Is the canonical implementation reused? See the table in AGENTS.md.
• Failure modes: are errors handled with context, retries bounded, timeouts set?
• Do tests cover the behaviour that changed, not only the lines that changed?
• For Compose, chart, or .env.example changes: does the first-install path still work?

Security, as part of the structural pass

• Is new external input validated before use?
• Are auth, authorization, and audit helpers used through their existing boundaries rather than re-implemented?
• Does the change widen permissions, scopes, or network exposure? If so, is the wider grant necessary?
• Are new dependencies and actions pinned, and free of secrets or environment-specific identities?

Narrative

• Does the description say why, link the issue, and state how the change was verified?

Style preferences that no linter enforces are non-blocking comments. Say so when leaving one.

AI-assisted contributions

• Disclose AI assistance in the pull request description.
• The author is responsible for every line submitted, whatever produced it.
• Do not add AI co-author or assisted-by trailers. Signed-off-by is a human certification — see the DCO policy in AGENTS.md.

Automated first pass

Maintainer review starts only after CI checks complete successfully. An AI reviewer provides advisory feedback on non-draft pull requests and may run in parallel with maintainer review.

• It is advisory. It never approves, never blocks a merge, and its review never counts as the maintainer approval.
• Authors should address relevant bot findings; maintainers may dismiss them.
• An unavailable or incomplete automated review does not delay human review or merge.
• Existing PR discussions about dismissed findings may inform the evaluation; no separate record is required.
• Its configuration lives in this repository: low-noise profile, AGENTS.md as its rule source, generated files excluded, drafts and WIP titles skipped.

Governance, before any such tool is enabled:

1. An install request naming the tool, the repository, and the permissions it needs.
2. A recorded assessment of its permissions, data handling, models, retention, and security certification.
3. A 90-day pilot, scoped to this repository.
4. After 90 days, maintainers decide whether to continue, adjust, or remove the tool using available vendor reports and existing PR discussions. Before starting the pilot, confirm which reports are included in the free OSS offering. Reviewers are not required to submit feedback or maintain additional records. Reported acceptance rates and estimated time savings are supporting indicators, not proof of improved review quality. If the available evidence is insufficient, record that limitation in the evaluation.

CodeRabbit assessment

Published documentation checked on 2026-09-26. Confirm these details again before installation; service terms and limits can change.

Topic	Published facts and implications for CAIPE
Installation	An org owner can install the managed GitHub App for this repository only. Contributors do not need their own installation. Source
Permissions	Read access to Actions, discussions, members, metadata, and merge queues; read/write access to checks, code, commit statuses, issues, PRs, and workflows. Code and workflow write access are broader than advisory review needs. Disabling automated edits does not remove those permissions. Source
Code processing	CodeRabbit says code is shared with OpenAI and/or Anthropic for review and is not used for model training. These are vendor statements. Source
Retention	Review caches expire within seven days; the documentation excludes OSS caches from its encryption guarantee. The pilot sets reviews.disable_cache: true and opts out of retained knowledge-base data. File-based AGENTS.md guidelines remain enabled. Other stored review context and logs need separate assessment; seven days is not a universal retention limit. Source
Cost and limits	Current documentation offers Team features free for OSS, without a paid contributor subscription. OSS limits vary by project and are separate from the ordinary Free plan. Confirm assigned review/file limits and included reports before installation. Source
Fit for CAIPE's volume	The epic records 136 merges in 30 days. That does not establish review demand: repeated pushes consume reviews, and large PRs may exceed file limits. The pilot should remain within the free offering. Epic measurement

Before installation, the org owner confirms the requested permissions, applicable data-retention terms, assigned OSS limits, and available reports. Any unresolved limitations are recorded in the installation request.

Approval

• One maintainer approval is required to merge.
• A bot review is never an approval.
• Address review feedback or reply explaining why not; do not leave threads unanswered.
• Apply review suggestions locally. Do not use GitHub's Commit suggestion button: the commit it creates names the suggestion's author as a co-author who has not signed off, so the DCO check fails.

Review capacity

• Maintainers sweep pull requests with no review at least weekly. Each one gets a reviewer or a comment naming what blocks it.
• Stale handling is unchanged: the stale bot marks inactivity and closes after the configured grace period.

Adoption status

Item	State
This policy and checklist	in effect
Pull request size guidance	in effect
Size labels on pull requests	in effect; open PRs backfilled
Automated first pass	90-day pilot since 2026-09-28; evaluation due 2026-12-27 (#2804)
Backlog triage sweep	not planned; covered by the weekly sweep under Review capacity