Pre-Merge Checklist

Before merging: ensure these.

What goes in the checklist

The checklist covers four dimensions: tests, review, docs, observability. Bounded to those four; longer lists overwhelm reviewers and get ignored within a quarter.

• Tests. Unit, integration, end-to-end where applicable; CI green before review begins.
• Code review. At least one approver; ideally two for tier-1 services where blast radius justifies the pair check.
• Documentation. Non-obvious-code comments and runbook updates; updated when behaviour changed, not added later.
• Observability. New metrics, alerts, and dashboards added with the feature, not after the first incident exposes the gap.

Automate what you can

Automation enforces the boring parts so reviewers can spend attention on the parts that matter. Branch protection, PR templates, and bot checks together cover most of the mechanical layer.

• Branch protection. Require CI and review; GitHub or GitLab native blocks merges without them.
• PR templates. Checkbox-required template per repo; documentation, tests, observability boxes visible at PR creation rather than as a post-merge afterthought.
• Bot checks. Linked-ticket state and description-format check per PR; reduces reviewer cognitive load on procedural items.
• Documented intent per rule. Named "why this rule exists" note per rule; reflexive disabling is the failure mode without it.

What humans must check

Some checks resist automation. Logical correctness, API design, and performance/security implications all require human attention; tools surface symptoms but miss the architectural patterns.

• Logical correctness. "Tests pass but the code is still wrong" check; the kind of thing tools cannot replace.
• API design. Breaking-change acknowledgement per PR; changes to public APIs need explicit reviewer attention and explicit versioning.
• Performance and security. Implications automated tools miss; often subtle and need human eyes that have seen similar patterns before.
• Named primary reviewer per PR. Responsible reviewer per PR; "everyone reviewed, no one really did" is the failure mode.

Blockers vs nits

Distinguish blockers from nits explicitly. Blockers must land before merge; nits are follow-up suggestions. The convention reduces review friction and prevents nit comments from feeling like merge gates.

• Blocker. Must-fix-before-merge tag per comment; test failures, security findings, breaking API changes without versioning.
• Nit. Nice-to-have-can-be-follow-up tag per comment; style preferences, naming, refactoring opportunities.
• Distinguish in review. Explicit "blocker" or "nit" prefix per comment; reduces ambiguity that wastes both author and reviewer time.
• Documented categorisation per team. Published "what counts as blocker" guide; supports consistent reviews across reviewers.

How to roll out the checklist

Roll out with three pieces: bounded item count, PR template integration, and quarterly audit. Long checklists fail at adoption; short ones miss the point.

• Start with three items. Bounded checklist per team; 20-item checklists overwhelm reviewers and get reflexively ignored.
• Bake into PR template. Visible-at-creation checklist per repo; hard to skip when the template surfaces it.
• Quarterly audit. 10-random-merge review per quarter; check checklist quality and adjust based on what slipped through.
• Named owner per team. Responsible engineer per team; "everyone-and-no-one" follow-up on the audit is the failure mode.