| # 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][code-owners] page. |
| |
| ## Format |
| |
| Fuchsia uses the [Gerrit file syntax][owners-syntax] for `OWNERS` |
| files. |
| |
| Here's an example `OWNERS` file: |
| |
| ```none |
| # 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. CL |
| authors can add owners-override@fuchsia.dev to the reviewer list to |
| request owners override. This process should be used sparingly and |
| review by local owners is preferred whenever it does not present and |
| undue burden on developers. |
| |
| [code-owners]: https://android-review.googlesource.com/plugins/code-owners/Documentation/index.html |
| [owners-syntax]: https://android-review.googlesource.com/plugins/code-owners/Documentation/backend-find-owners.html#syntax |
