OWNERS File Governance

Recursive directory-scoped code-review authority: each directory may carry an OWNERS file naming the engineers whose LGTM the commit queue requires before merging any change in that directory or its subdirectories.

“Every directory in Chromium has an OWNERS file (or inherits one from a parent directory). … An owner LGTM is required to land a change.” — Chromium project, docs/code_reviews.md

The word “owner” in Chromium carries at least three regimes. A “feature owner” is the engineer accountable to their team for shipping a specific feature. An “API owner” is a member of the small Blink standing population whose LGTM on a blink-dev Intent thread is what clears the Three-LGTM API Owner Gate. An OWNERS file entry is neither: an address listed in a per-directory text file whose authority is constituted by the file itself, scoped recursively from that directory down, and exercised through a one-line LGTM reply on Gerrit. Treating the three regimes as one term is how new contributors discover that their CL’s been waiting on the wrong reviewer’s attention for a week.

Context

This pattern sits at the operational layer of Chromium’s coordination machinery. It is what a contributor encounters the first time they upload a change to Gerrit and watch the system route the review. Above it lie the standards-body and governance-body patterns of the Intent to Ship Pipeline and the Three-LGTM API Owner Gate; alongside it sit the on-call coordination patterns of Tree Sheriff and Perf Sheriff; underneath it sit Gerrit and the commit queue. The pattern is the load-bearing rule that gates every line of code the project merges.

The reader who needs it most is a contributor from a downstream organization (Microsoft Edge, Igalia, Intel, Samsung, an enterprise browser vendor, an Electron application author) uploading their first CL and trying to understand why the review is routing to a specific set of accounts. The pattern also speaks to the CIO and the Head of Engineering at organizations evaluating contribution cost: an estimate of the coordination overhead of any planned Chromium contribution begins with reading the OWNERS files for the target directories.

Problem

Chromium is a roughly seventeen-year-old, fifty-million-line, multi-organization codebase. Any merge-queue policy that requires global review across all contributors stalls; any policy that lets any contributor merge any change loses the institutional knowledge that keeps the project coherent. The project needs a code-review authority regime that is mandatory, fine-grained, locally appropriate, and routable without a central coordinator. It also needs the regime to scale to several hundred active contributors a day and to encode, durably, who carries the relevant context for each subsystem the project ships.

The recurring difficulty is that the answer cannot be hidden behind an opaque routing service. New contributors need to read the rule before they upload a change. Long-term contributors need to revise the rule when staffing shifts. Downstream organizations need to read the rule to estimate where their contributions will route. Auditors need to read the rule to verify that the review surface is not concentrated in one person or one team. The rule has to be both binding and legible.

Forces

• Authority must be local but verifiable. The reviewers for gpu/ should not be the reviewers for accessibility/; the project should not invent a central authority that signs off on every change; but every CL’s required-approver set must be derivable mechanically from the change’s file paths.
• Membership must be revocable without ceremony. People rotate teams, change employers, leave the project. The mechanism that adds and removes reviewer authority must run at the same cadence as the staffing changes it tracks.
• Inheritance must be predictable. A reviewer’s authority should extend to subdirectories by default so that the project does not need a separate OWNERS file for every leaf folder; the rule for when a subdirectory’s OWNERS overrides versus extends the parent must be one a contributor can apply at a glance.
• The mechanism must be auditable. A contributor, an auditor, an AI coding agent, or a downstream-vendor security team should be able to read, from the source tree alone, who can authorize a change in any subtree. The authority record cannot live in a closed ticketing system or a private wiki.
• The mechanism must be cheap to consult. Gerrit’s CL view should be able to compute the required-approver set and the satisfied-approver set in milliseconds; the contributor uploading a change should see the routing before they type a description.

Solution

Place an OWNERS file in each directory whose contributors carry distinct review authority. The file is plain text. Each line is either an email address granting LGTM authority to its holder, or a directive that modifies inheritance or scoping. The Gerrit find-owners plugin reads the file when a CL is uploaded, computes the union of authority required across the change’s paths, and surfaces the required-approver set in the review UI. A CL clears the OWNERS-LGTM gate when at least one address from the required-approver set has posted LGTM on the change; the commit queue refuses to merge until the condition holds.

The mechanism uses four scoping rules.

Recursive inheritance. An OWNERS file at content/browser/ extends to every subdirectory and file under content/browser/ unless a more-specific OWNERS file overrides. A change touching content/browser/renderer_host/render_widget_host.cc requires LGTM from the union of the OWNERS chain (the most-specific applicable file plus any parent files not gated by set noparent), computed at upload time.

set noparent. A directory whose OWNERS file begins with set noparent does not inherit from its parent. Use cases are security-sensitive subsystems (sandbox/, parts of crypto/) where the project deliberately narrows the reviewer set rather than letting parent OWNERS grant authority by inheritance. The directive is a hard scoping boundary.

per-file directives. A line like per-file *.fidl=alice@example.com grants alice@example.com LGTM authority for the matching files in the directory without granting it for the directory at large. The mechanism handles the common case of a contributor whose authority is specific to one file type, one build configuration, one platform path, or one feature flag without forcing the project to fragment the directory itself.

file:// inheritance. A line like file://path/to/OWNERS_FILE inherits authority from another path in the source tree. The use case is a subsystem (the Mojo IPC interfaces, the Web IDL bindings, the Polymer-derived UI components) whose authority should track a single canonical roster regardless of where the implementation lives in the directory tree. The directive turns OWNERS into a small graph rather than a strict tree.

OWNERS file membership is added or removed through a Gerrit change to the OWNERS file itself, reviewed and LGTM’d by the file’s current owners. There is no separate management interface; the file is the source of truth and the revision history is the audit trail.

How It Plays Out

A new contributor at Igalia is uploading their first CL to Gerrit. The change touches three files: a CSS rendering header under third_party/blink/renderer/core/css/, a related implementation under third_party/blink/renderer/core/layout/, and a test under third_party/blink/web_tests/css/. Gerrit’s find-owners plugin computes the required-approver set: one LGTM from a current owner of core/css/, one from a current owner of core/layout/, and (because the web-tests OWNERS file uses set noparent) one from a current owner of web_tests/css/ specifically. The contributor adds the suggested reviewers from each set, posts the change with a description sufficient for asynchronous evaluation, and the routing is decided before any human reviewer reads the CL. The three LGTMs arrive over thirty hours; the commit queue picks up the change on the next cycle.

A downstream enterprise-browser vendor is evaluating whether to upstream a fix their team developed for a performance regression in the GPU compositor. The vendor’s engineering lead reads the OWNERS files for the relevant subdirectory and discovers the reviewers are split between Google’s graphics team and Intel’s hardware-acceleration team. The lead identifies the organizations from the email-domain distribution in the file, engages Intel through a previously-established channel before posting the CL publicly, and routes the upstream conversation to align with the OWNERS map. The CL lands with less friction than a comparable patch in a Google-only subdirectory would have, because the organizational fit was favorable and visible from the OWNERS file alone. Conway’s Law in Multi-Org Chromium names the broader pattern; this CL is one operational instance of it.

A senior contributor at Microsoft Edge is rotating onto the OWNERS roster for a subdirectory their team has staffed for two years. The change is a one-line addition to the OWNERS file at chrome/browser/enterprise/, reviewed and LGTM’d by the file’s existing owners. The contributor’s authority over the directory takes effect on the change’s submission; no separate provisioning, no role assignment, no membership table. Two weeks later, a Google contributor who had been the only Google-side owner of the same directory rotates off the team; their address is removed from the file in another one-line CL. The directory’s authority shifts from “Google-only” to “Google + Microsoft Edge” in the source tree’s revision history; downstream readers can see the shift from git log on the file.

Consequences

Benefits. The mechanism is one of the project’s most legible coordination surfaces. A contributor preparing a change can predict the required-approver set before uploading, which removes a class of “who reviews this?” friction that other large codebases routinely produce. A downstream organization can read the source-tree distribution to assess where their contributions will route, which feeds the coordination-cost estimates a CIO needs to budget upstream effort. The audit trail is durable: every grant and revocation of authority is in the Gerrit history of the relevant OWNERS file, signed by the reviewers who approved it.

The mechanism scales with the project. Each new directory carries its own authority record; the project does not centralize membership in any list or service that grows past the size a contributor can read. The file:// directive handles the small set of subsystems whose authority crosses the strict directory tree; the per-file directive handles the common case of file-type-scoped authority without forcing directory fragmentation; set noparent handles the security-sensitive case where the project deliberately narrows authority.

The mechanism encodes Conway’s Law into a queryable artifact. git grep "@igalia.com" over the OWNERS files returns Igalia’s formal authority across the source tree; the same grep over @microsoft.com, @intel.com, @samsung.com, or other contributing-organization domains produces the corresponding maps. Conway’s Law in Multi-Org Chromium treats the maps as primary evidence; the OWNERS files are where the evidence lives.

Liabilities. The mechanism encodes only formal authority, not responsiveness. An OWNERS entry whose holder is on parental leave, who has rotated to a different team without removing themselves from the file, or who is overloaded doesn’t announce any of that in the file. A contributor who routes a CL to the OWNERS roster discovers reviewer responsiveness only through experience; the formal record is silent. The Formal-Informal Channel Split names the broader pattern that explains why: information about which OWNERS are responsive lives in the informal channels (Slack, internal team chats, the senior contributor’s tacit knowledge), and the formal OWNERS file does not encode it.

The mechanism produces a coordination bottleneck in subdirectories with a thin OWNERS roster. A directory whose OWNERS file lists three people, one of whom is on extended leave and one of whom is overloaded, accumulates CLs faster than the remaining reviewer can clear them. The project’s response (periodic additions to the roster, sometimes from organizations that previously had no representation in the directory) is partial and time-lagged.

The mechanism interacts with the Tree Sheriff bypass authority in a way that surprises contributors. A Tree Sheriff can revert a landed change without obtaining its OWNERS’ LGTM; the revert is procedurally legitimate but cuts across the directory-scoped authority regime the OWNERS file otherwise establishes. The mechanism doesn’t announce the interaction; a contributor learns it the first time their CL is reverted by a Tree Sheriff whose name isn’t in any relevant OWNERS file.

The mechanism is silent on the cross-cutting concerns that the Three-LGTM API Owner Gate operates over. A web-platform-visible change can clear every directory OWNERS LGTM in its path and still fail to reach Stable because the API-owner regime hasn’t granted its three LGTMs. The two regimes use the same four-letter token and the same Gerrit interface, and conflating them is the most common failure mode the API Owner concept exists to disambiguate.

Notes for Agent Context

Before proposing a Chromium contribution, read the OWNERS file for each file path the change touches and compute the required-approver set from the file itself; don’t infer it from the directory name, from prior CLs in adjacent subtrees, or from organizational seniority. Treat set noparent, per-file, and file:// directives as the project’s deliberate scoping rules, not as exceptions to ignore: a parent OWNERS entry grants no authority into a set noparent subdirectory, and per-file and file:// lines narrow or redirect authority on the project’s terms. When surfacing reviewers to the human contributor, name the OWNERS-file paths the change touches so the routing can be verified, and never select reviewers from outside the computed approver set even when the change looks small. Never confuse OWNERS LGTMs (directory-scoped, granted in the Gerrit code-review thread) with API-owner LGTMs (cross-cutting, granted on the blink-dev Intent thread); a web-platform-visible change requires both regimes’ authority independently, and code-level approval doesn’t substitute for the gate the Three-LGTM API Owner Gate names.

Related Patterns

Sources

The canonical source for the OWNERS mechanism is the Chromium project’s own code-review documentation, currently maintained as docs/code_reviews.md on chromium.googlesource.com, with the file syntax and scoping rules covered in docs/code_review_owners.md and the find-owners plugin’s reference behavior documented in the Gerrit project’s own pages. The mechanism’s intellectual lineage is older than Chromium: directory-scoped reviewer lists appear in Mozilla’s CVS-era code-review practices and in Linux kernel MAINTAINERS file conventions, both of which predate Chromium and informed the project’s choice when the file was introduced in the mid-2000s. The Gerrit project’s find-owners plugin is the implementation surface; the plugin’s documentation and source live in the Gerrit Code Review project repositories. Brian Fitzpatrick and Ben Collins-Sussman’s Team Geek (O’Reilly, 2012) treats directory-scoped ownership as a coordination pattern with named tradeoffs; their treatment is general but the Chromium specialization follows the shape they describe. Conway’s Law in Multi-Org Chromium treats the OWNERS files as the most operationally legible expression of the contributing-organization distribution, and its empirical mapping is grounded in the same source tree this pattern names.

Technical Drill-Down

• docs/code_reviews.md — the project’s canonical code-review documentation; the OWNERS regime is named in the opening sections and the LGTM gate is stated explicitly.
• docs/code_review_owners.md — the OWNERS file syntax, scoping rules, set noparent semantics, per-file directives, and file:// inheritance; the operational reference.
• Gerrit find-owners plugin — the implementation surface that computes the required-approver set from a CL’s file paths; behavior here is what Gerrit displays to the contributor.
• chromium/src repository (Gitiles) — the primary source tree; find . -name OWNERS over a checkout returns the full set of files, currently several thousand, that constitute the project’s distributed authority record.
• docs/contributing.md — the new-contributor onboarding document that names the OWNERS regime as one of the load-bearing project conventions a first-time contributor must understand.
• Team Geek, Brian Fitzpatrick and Ben Collins-Sussman, O’Reilly, 2012 — the general treatment of directory-scoped ownership as a coordination pattern, with the named tradeoffs that the Chromium specialization realizes.