Code Review, Suggested Changes, CODEOWNERS, Review Requests, and Review Discipline: Configuration, Design Choices, and Tradeoffs

1. CODEOWNERS granularity: map responsibility, not the directory tree mechanically

The best CODEOWNERS file is not the one with the most lines. It is the one whose patterns correspond to people who can actually make informed decisions. If every tiny directory has a different owner, simple refactors can request a dozen reviewers. If one global team owns everything, critical domain expertise becomes invisible. Start with architectural boundaries—payments, identity, deployment, documentation—and refine only when responsibility is stable.

2. User ownership versus team ownership

A personal repository can list individual users with write access. Organization repositories can list visible teams in the form @org/team; the team itself must have write access even if every member separately has access. Team ownership scales better because membership changes do not require editing CODEOWNERS, but it introduces organization administration and team-visibility dependencies.

3. Automatic owner routing versus required owner approval

Automatic CODEOWNERS review requests answer “who should look?” Required code-owner review answers “whose approval must exist before this protected target may merge?” Use the stronger gate only where ownership is genuinely part of change authorization. Requiring owners for low-risk formatting or generated files can create avoidable queues and pressure reviewers to rubber-stamp.

4. Freshness policy: dismiss stale approvals or require latest-push approval?

These controls answer slightly different threats. Dismissing stale approvals favors strong proof that the current diff has been reviewed; every relevant post-approval change can require reapproval. Requiring approval of the most recent reviewable push focuses on preventing the latest pusher from adding unreviewed content while retaining earlier approval history. GitHub explicitly describes the latter as a compromise for complex PRs with many reviewers and the former as safer when PR hijacking is a concern.

5. “Last push” is not the same as “last commit author”

The policy asks for approval from someone other than the person who most recently pushed the reviewed changes. Treat it as a hosted review-control identity rule, not a Git author-email rule. A maintainer applying a suggestion, a bot updating a branch, or an author pushing a follow-up can change who performed the latest push even when commit authorship differs. Always inspect current PR/review evidence rather than guessing from git log alone.

6. Review etiquette: severity must be visible in the feedback

A disciplined team should not make authors decode whether “maybe rename this” blocks a production release. Define a small language for intent. For example, blocking identifies correctness/security/operability issues that must change; non-blocking suggests improvement that can be accepted, deferred, or tracked separately; question requests explanation; nit is cosmetic and should never masquerade as a gate.

[blocking] This retry loop can run without an upper bound during provider failure.

[non-blocking] Consider extracting this parser after the release; current scope is acceptable.

[question] Which runbook documents the fallback when this dependency is unavailable?

[nit] Rename local variable for consistency; no merge block.

7. Response SLA: optimize latency without incentivizing shallow approvals

Review service-level expectations should describe response latency, not force instant approval. A production policy might say: acknowledge high-priority review requests within four working hours; complete normal reviews within one working day; security-critical changes require two domain reviewers; authors re-request review after material changes. The exact numbers are team policy, not GitHub product constants. Keep them realistic enough that reviewers can actually inspect the change.

8. Do not use automated checks to erase human responsibility

If lint, unit tests, or security analysis can answer a question reliably, automate it so reviewers spend attention on intent and risk. But do not convert “checks pass” into “human review unnecessary” when the change affects architecture, permissions, failure behavior, or sensitive workflows. Conversely, do not waste reviewer time enforcing formatting rules that a deterministic tool can verify.

9. Worked design scenario: payment service in a mixed repository

Assume a public GitHub repository has services/payments/, services/catalog/, docs/, and .github/workflows/. Payments changes can move money; workflow changes can alter CI privileges. The team wants reasonable throughput without weakening these boundaries.

The important output is the reasoning. Another team may select different controls if its release cadence, threat model, staffing, or repository topology differs.

10. Product boundaries and deployment differences

• Core Git: commits, branches, merge bases, and diffs. Git has no CODEOWNERS or approval state.
• GitHub hosted review: review requests, dispositions, conversations, suggestions, CODEOWNERS matching, branch protections/rulesets.
• GitHub Actions/checks: automated evidence that may be required separately by branch policy.
• GitHub.com plans: public repositories support CODEOWNERS, protected branches, and rulesets on Free; private availability requires eligible paid plans.
• GitHub Enterprise Server: verify the installed GHES version documentation before applying GitHub.com-era options or API versions.
• External CI/security tools: can publish checks/statuses but do not become GitHub human review state.

11. Lesson summary

Good review policy routes the right expertise, applies stronger gates only where justified, defines how approvals age, and makes feedback severity explicit. The goal is high-signal review with defensible freshness—not maximizing the number of mandatory clicks.

Knowledge check

Authoritative references

• About code owners
• Requesting a pull request review
• About protected branches
• Managing a branch protection rule
• Available rules for rulesets
• About rulesets
• About pull request reviews
• Incorporating feedback in your pull request