PR Guidelines

Источник: dev/fera/community/PR-GUIDELINES.md (read-only; сгенерировано scripts/sync-docs.mjs)

PR Guidelines

What a pull request must contain to be reviewed, across all repositories in the the-fera org.

Before you open

• The branch builds and the full test suite passes locally.
• The change is split into focused commits (see COMMIT-STYLE.md) — one logical change per commit, not one mega-commit.
• If the change implements or touches a decision from the design corpus (ADR/OQ), you have re-read the relevant entry. The docs are the authority; if reality disagrees with a doc, the PR is the place to surface that — with an explicit note, not a silent divergence.

PR contents (required)

1. What & why. One paragraph: what the PR changes and the reason it exists. If there is an issue, Closes #N.
2. How. The design of the change — the interesting decisions, not a diff narration. What alternatives were rejected and why.
3. Tests. New/changed behavior is covered. If coverage was impossible, say so and why — an honest gap beats a fake green.
4. Benchmarks (for perf-shaped PRs). Before/after numbers, scene, hardware. No benchmark, no merge.
5. Corpus updates. Behavior-shaping changes update the relevant ADR/OQ entry in the same PR, or declare it a follow-up with an issue link.

Review expectations

• Reviews are about code and design, not persons. Disagree with arguments, not tone.
• The reviewer’s job is to find what the author missed — reviewers are expected to actually read the diff, not rubber-stamp.
• The author responds to every review comment: fix it, push back on it, or link why it’s out of scope. Silence is not a response.
• Approvals: one for regular changes; a second maintainer for anything crossing a module contract (trait boundary, manifest schema, ABI shape) — these are the hardest things to undo later.

Project-specific gates

These are hard gates, enforced in review and CI — not best-effort:

Gate	Rule	Source
Contract tests	No second impl of a trait merges without its contract-test suite	ADR-014
Audit table	New persisted fields carry an ADR-031 tier assignment in the same PR	ADR-031
Benchmark proof	Every optimization PR references a reproducible benchmark	OQ-024
Batch-first traits	Any trait crossing a hot module boundary is batch-shaped	ADR-005
No raw TL leaks	No grammers/TL types above the protocol layer	RFC §4.1

Size guidance

Small PRs merge faster and review better. If your change is naturally large, split it into a stack (base → … → head) where each level builds and passes tests on its own. A reviewer should be able to hold one level’s context in their head.