Code Ownership & Project Boundaries

## What the file is A CODEOWNERS file is a plain-text convention (supported natively by GitHub, GitLab, and Bitbucket, and implemented independently by tools like Google's internal OWNERS files and Gerrit) that lives at a fixed path in a repository — typically `.github/CODEOWNERS`, `.gitlab/CODEOWNERS`, or the repo root — and maps **file-path glob patterns** to one or more **owners**, where an owner can be an individual username or a team/group handle. A typical line looks like `/services/payments/ @org/payments-team`, meaning any file under that directory is 'owned' by the payments team. ## How a pull request is matched The mechanism itself is simple. Whenever someone opens a pull request, the hosting platform: 1. diffs the PR against the target branch; 2. walks every changed file path; 3. for each one finds the *last* matching pattern in the CODEOWNERS file — patterns are evaluated top-to-bottom, and, like a `.gitignore` file, a later, more specific pattern overrides an earlier, more general one. The **union of owners** for all matched patterns across the whole diff becomes the set of reviewers the platform automatically requests. ## From convenience to policy By itself, that's just a convenience — it saves someone from manually figuring out who to ping. The mechanism becomes a real *policy* only when paired with a **branch protection rule**, commonly labeled 'Require review from Code Owners,' on the target branch. - **With that rule enabled**, the merge button is disabled until at least one person from every matched owner group has submitted an approving review — this is what makes CODEOWNERS a hard gate rather than a suggestion. - **Without that rule**, CODEOWNERS is purely advisory: reviewers get auto-requested, but anyone with merge permission can still merge without their approval. ## Why it exists The reason this exists is that as a codebase and organization grow, 'everyone reviews everything' doesn't scale — most engineers in a large monorepo have neither the context nor the standing to meaningfully review a change to a module they've never touched, and asking them to try produces rubber-stamp approvals or bottlenecks on whoever happens to be online. CODEOWNERS routes review responsibility to the people who actually understand a given area, automatically, without relying on the PR author to remember who that is — which matters especially for new hires and cross-team contributors who don't yet know the informal ownership map. ## The trade-off The trade-off is that CODEOWNERS only governs who must approve a merge, nothing else. - It **does not restrict who can open a PR** against those files — anyone with write access can propose the change. - It **doesn't prevent another module from importing** or depending on owned code — that's a build-time concern handled by separate tooling (visibility rules, module-boundary linting). - It **doesn't validate that the reviewer actually understood the change**; a rubber-stamp approval satisfies the gate exactly as well as a careful review. So CODEOWNERS solves the 'who reviews this' routing problem but nothing about review quality or architectural correctness. ## Failure modes Failure modes recur in a few recognizable ways. - **Individual-named owners** (`@jane` rather than `@team-x`) create single points of failure: if Jane is on leave or has left and the entry wasn't updated, every PR touching that path stalls with no automatic fallback — most platforms have no 'escalate after N days' behavior, so this needs team-based entries or a monitoring bot. - **Precedence bugs** are common: someone adds a more specific pattern below an old one expecting it to be additive, not realizing it fully overrides the earlier match, silently changing who's asked to review. - **At scale**, CODEOWNERS files often balloon to thousands of lines nobody maintains carefully, drifting out of sync with actual team boundaries after reorgs. - **Coarse ownership** over widely-shared code turns a small owning team into an organization-wide bottleneck, since every consumer's PR routes through the same reviewers regardless of triviality. ## Where the convention came from A well-known real-world instance predates GitHub's native support: Chromium and many Google-internal repositories use `OWNERS` files with essentially the same semantics — per-directory ownership, inherited down the tree unless overridden, enforced by Gerrit's review tooling before a change can land — which is part of why GitHub's CODEOWNERS feature later adopted such similar syntax and behavior.