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.
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:
OWNERS file that disables inheriting code owners from parent directories via the set noparent file-level rule (example)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).
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:
/foo/bar/OWNERS/foo/OWNERS/OWNERS/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.
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:
/foo/bar/OWNERS/foo/bar/OWNERS/foo/OWNERS/foo/OWNERS/OWNERS/OWNERS/OWNERS in refs/meta/config (contains default code owners)/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.
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.
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
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.
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
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.
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.
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.
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:
OWNERS file with only set noparent (ignores code owners from parent directories, but doesn't define code owners that should be used instead)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)OWNERS file at root levelNOTE: How to exempt files from requiring code owner approval is described here.
Back to @PLUGIN@ documentation index
Part of Gerrit Code Review