Owners

Each file in Fuchsia has a set of owners. These are tracked in files named OWNERS. One of these files is present in the root of the repository, and many directories have their own OWNERS files too.

Contents

Each OWNERS file lists a number of individuals (by their email address) who are familiar with and can provide code reviews for the contents of that directory.

Responsibilities

Fuchsia requires changes to have an Code-Review +2 review, which anyone in the OWNERS file can provide. In addition, many OWNERS files contain a * allowing anyone to provide such a +2.

Tools

Gerrit has a "suggest owners" button that will list all the owners for all the files modified in a given change. More information on this is available on the Gerrit code-owners plugin page.

Format

Fuchsia uses the Gerrit file syntax for OWNERS files.

Here's an example OWNERS file:

# These users are owners
validuser1@example.com
validuser2@example.com

# Users listed elsewhere are also owners
include /path/to/another/OWNERS

# This user is only an owner of the listed file
per-file main.c = validuser3@example.com

Best practices

  • It's important to have at least two individuals in an OWNERS file. Having areas of Fuchsia with a single owner leads to single points of failure. Having multiple owners ensures that knowledge and ownership is shared over areas of Fuchsia.

  • When applicable, include owners from another file rather than listing individuals. This creates fewer "sources of truth" and makes OWNERS maintenance easier.

Owners override

In some cases, the author of a change may wish to override OWNERS approval. This is appropriate primarily in cases where a change is mostly mechanical but touches a large fraction of the codebase (for example, a trivial change to the signature of a commonly used API).

To request an owners override, follow these steps:

  1. Verify eligibility: Ensure the change is appropriate for an override. This process should be used sparingly; review by local owners is preferred whenever it does not present an undue burden on developers.

  2. Add the override reviewer: Add owners-override@fuchsia.dev to the reviewer list in your Gerrit change.

However, when you need to add or update an OWNERS file, it is preferred to manage these changes within a dedicated Gerrit change. This approach is preferred because it enables owner-override and allows the file to be submitted on its own. By keeping it separate, you also avoid the need of re-stamping the OWNERS modification if other parts of the Gerrit change require additional changes. This process is commonly used when introducing new directories, for example, in //src or //src/lib.