find-owners: Cookbook for OWNERS files

For the find-owners backend code owners are defined in OWNERS files. This cookbook provides examples of OWNERS files for various use cases.

NOTE: The syntax of OWNERS files is described here.

Define users as code owners

To define a set of users as code owners, each user email must be placed in a separate line:

  jane.roe@example.com
  john.doe@example.com
  richard.roe@example.com


The order of the user emails is not important and doesn't have any effect, but for consistency an alphabetical order is recommended.

The listed users own all files that are contained in the directory that contains this OWNERS file, except:

  • files in subdirectories that have an OWNERS file that disables inheriting code owners from parent directories via the set noparent file-level rule (example)
  • files that are matched by a path expression in a per-file line that uses set noparent (in this OWNERS file or in any OWNERS file in a subdirectory, example)

In addition to the specified owners the files are also owned by the code owners that are inherited from the parent directories. To prevent this the set noparent file-level rule can be used (see next example).

Ignore parent code owners

To ignore code owners that are defined in the OWNERS files of the parent directories the set noparent file-level rule can be used:

  set noparent
  jane.roe@example.com
  john.doe@example.com
  richard.roe@example.com


For example, if code owners for the file ‘/foo/bar/baz.txt’ are computed the OWNERS files are evaluated in this order:

  1. /foo/bar/OWNERS
  2. /foo/OWNERS
  3. /OWNERS
  4. /OWNERS in refs/meta/config (contains default code owners)

If any set noparent file-level rule is seen the evaluation is stopped and further OWNERS files are ignored. E.g. if /foo/OWNERS contains set noparent the OWNERS files mentioned at 3. and 4. are ignored.

NOTE: When the set noparent file-level rule is used you should always define code owners which should be used instead of the code owners from the parent directories. Otherwise the files in the directory stay without code owners and nobody can grant code owner approval on them. To exempt a directory from requiring code owner approvals, assign the code ownership to all users instead (example).

NOTE: The usage of set noparent has no effect on OWNERS files in subfolders.

Define code owners for a certain file

By using the per-file restriction prefix it is possible to define code owners for a certain file (in the current directory and all its subdirectories), e.g. for the BUILD file:

  per-file BUILD=tina.toe@example.com


Multiple code owners for the same file can be specified as comma-separated list:

  per-file BUILD=tina.toe@example.com,martha.moe@example.com


Alternatively it's also possible to repeat the per-file line multiple times:

  per-file BUILD=tina.toe@example.com
  per-file BUILD=martha.moe@example.com


If a file is matched by the path expressions of multiple per-file lines, the file is owned by all users that are mentioned in these per-file lines.

If folder code owners are present, the file is also owned by any folder code owners:

  jane.roe@example.com
  john.doe@example.com
  richard.roe@example.com
  per-file BUILD=tina.toe@example.com,martha.moe@example.com


In addition, the file is also owned by code owners that are inherited from parent directories.

Ignoring folder code owners and inherited parent code owners for a file is possible by using a matching per-file line with set noparent.

  jane.roe@example.com
  john.doe@example.com
  richard.roe@example.com
  per-file BUILD=set noparent
  per-file BUILD=tina.toe@example.com,martha.moe@example.com


For example, if code owners for the file ‘/foo/bar/baz.txt’ are computed the code owners in the OWNERS files are evaluated in this order:

  1. matching per-file code owners in /foo/bar/OWNERS
  2. folder code owners in /foo/bar/OWNERS
  3. matching per-file code owners in /foo/OWNERS
  4. folder code owners in /foo/OWNERS
  5. matching per-file code owners in /OWNERS
  6. folder code owners in /OWNERS
  7. matching per-file code owners in /OWNERS in refs/meta/config (contains default code owners)
  8. folder code owners in /OWNERS in refs/meta/config (contains default code owners)

If any set noparent file-level rule is seen the evaluation is stopped and code owners on further levels are ignored. E.g. if /foo/OWNERS contains a matching per-file rule with set noparent the code owners mentioned at 4. to 8. are ignored.

NOTE: When the set noparent rule is used on a per-file rule you should always define code owners which should be used instead of the folder code owners and the code owners from the parent directories. Otherwise the matched files stay without code owners and nobody can grant code owner approval on them. To exempt matched files from requiring code owner approvals, assign the code ownership to all users instead (example).

NOTE: The syntax for path expressions / globs is explained here.

Define code owners for a certain file type

This is the same as defining code owners for a file only that the per-file line must have a path expression that matches all files of the wanted type, e.g. all ‘*.md’ files:

  per-file *.md=tina.toe@example.com


This matches all ‘*.md’ in the current directory and all its subdirectories.

NOTE: Using ‘*.md’ is the same as using ‘**.md’ (both expressions match files in the current directory and in all subdirectories).

NOTE: The syntax for path expressions / globs is explained here.

Define code owners for all files in a subdirectory

It is discouraged to use path expressions that explicitly name subdirectories such as my-subdir/* as they will break when the subdirectory gets renamed/moved. Instead prefer to define these code owners in my-subdir/OWNERS so that the code owners for the subdirectory stay intact when the subdirectory gets renamed/moved.

Nontheless, it's possible to define code owners for all files in a subdirectory using a per-file line. This is the same as defining code owners for a file only that the path expression matches all files in the subdirectory:

  per-file my-subdir/*=tina.toe@example.com

Define a group as code owner

Groups are not supported in OWNERS files and assigning code ownership to them is not possible.

Instead of using a group you may define a set of users in an OWNERS file with a prefix (<prefix>_OWNERS) or an extension (OWNERS_<extension>) and then import it into other OWNERS files via the file keyword.

/OWNERS_BUILD:

  jane.roe@example.com
  john.doe@example.com
  richard.roe@example.com
  per-file BUILD=tina.toe@example.com


other OWNERS file:

  per-file BUILD=file:/OWNERS_BUILD


This is equivalent to having:

  per-file BUILD=jane.roe@example.com,john.doe@example.com,richard.roe@example.com


NOTE: The per-file line from /OWNERS_BUILD is not imported, since the file keyword only imports folder code owners. Using the include keyword, that would also consider per-file code owners, is not supported for per-file lines.

Import code owners from other OWNERS file

To import code owners from another OWNERS file the file or include keyword can be used:

java/com/example/foo/OWNERS:

  jane.roe@example.com
  john.doe@example.com
  richard.roe@example.com
  per-file BUILD=tina.toe@example.com


javatests/com/example/foo/OWNERS:

  file:/java/com/example/foo/OWNERS


This is equivalent to having:

  jane.roe@example.com
  john.doe@example.com
  richard.roe@example.com


NOTE: The per-file line from java/com/example/foo/OWNERS is not imported, since the file keyword only imports folder code owners. If also per-line lines should be imported the include keyword can be used instead:

javatests/com/example/foo/OWNERS:

  include /java/com/example/foo/OWNERS


This is equivalent to having:

  jane.roe@example.com
  john.doe@example.com
  richard.roe@example.com
  per-file BUILD=tina.toe@example.com

Import code owners from other repository

To import code owners from an OWNERS file in another repository the file or include keyword can be used:

/OWNERS in the master branch of respository my-project:

  jane.roe@example.com
  john.doe@example.com
  richard.roe@example.com


/OWNERS in the master branch of respository my-project/plugin-foo:

  file:my-project:/OWNERS


This way my-project/plugin-foo always has the same code owners as my-project.

NOTE: If a branch is not specified, the OWNERS file will always be imported from the same branch, in which the importing OWNERS file is stored. If file:my-project:/OWNERS is contained in an OWNERS file in the master branch, my-project:master:/OWNERS is imported. If file:my-project:/OWNERS is contained in an OWNERS file in the stable-3.5 branch, my-project:stable-3.5:/OWNERS is imported.

Import code owners from other branch

To import code owners from an OWNERS file in another branch the file or include keyword can be used:

/OWNERS in the master branch of respository my-project:

  jane.roe@example.com
  john.doe@example.com
  richard.roe@example.com


/OWNERS in the stable-3.5 branch of respository my-project:

  file:my-project:master:/OWNERS


This way the stable-3.5 branch of my-project always has the same global code owners as the master branch of my-project.

NOTE: To import code owners from another branch it is mandatory to specify the repository, even if it is the same repository that contains the importing OWNERS file.

Exempt files from requiring code owner approval

To exempt files from requiring code owner approval the code ownership can be assigned to all users by using ‘*’ as user email. Assigning the code ownership to all users effectively exempts the directory (or the matches files if used in combination with a per-file rule) from requiring code owner approvals on submit. This is because a code owner approval from the uploader is always implicit if the uploader is a code owner.

OWNERS file that exempts the whole directory from requiring code owner approvals:

  *


OWNERS files that exempts all ‘*.md’ files (in the current directory and all subdirectories) from requiring code owner approvals:

  per-file *.md=*


NOTE: Files that are not owned by anyone are not excluded from requiring code ower approvals, see next section.

Avoid that files are not owned by anyone

Files that are not owned by anyone cannot be approved since there is no code owner that can grant the approval. Hence submitting modifications to them is only possible with an override approval.

Due to this it is recommended to avoid code owner configurations that leave files without code owners, e.g. the following configurations should be avoided:

  • an OWNERS file with only set noparent (ignores code owners from parent directories, but doesn't define code owners that should be used instead)
  • a per-file line with only set noparent (ignores folder code owners and code owners from parent directories, but doesn't define code owners that should be used instead)
  • no OWNERS file at root level

NOTE: How to exempt files from requiring code owner approval is described here.


Back to @PLUGIN@ documentation index

Part of Gerrit Code Review