Skip to content

Latest commit

 

History

History
397 lines (314 loc) · 17.2 KB

backend-find-owners.md

File metadata and controls

397 lines (314 loc) · 17.2 KB
Raw

find-owners Backend

The find-owners backend supports the syntax of the find-owners plugin (with some minor extensions). It is the backend that is used by default if no other backend is explicitly configured for a project or branch.

Code owner configuration

Code owners are defined in OWNERS files which are stored in the source tree.

The code owners that are defined in an OWNERS file apply to the directory that contains the OWNERS file, and all its subdirectories (except if a subdirectory contains an OWNERS file that disables the inheritance of code owners from the parent directories via the set noparent keyword).

NOTE: It is also possible to define code owners in <prefix>_OWNERS or OWNERS_<extension> files that can be imported into OWNERS files (further details about code owner config files are described here).

NOTE: Tools should never parse OWNERS files on their own, but instead always use the REST API to access code owner information.

Parsing OWNERS files is highly discouraged because:

  • it's hard for tools to implement the parsing of OWNERS files in a way that is consistent with how Gerrit parses them
  • reimplementing the parsing logic outside of Gerrit is a lot of effort that can be saved by using the REST API and letting Gerrit do the parsing
  • parsing OWNERS files outside of Gerrit is likely less efficient since the parser likely needs to reach out to Gerrit to fetch additional input (e.g. if OWNERS files from other branches or repositories are imported)
  • the format of OWNERS files may change (e.g. by the addition of new features) which could break parsers outside of Gerrit

Default code owners

Default code owners that apply to all branches can be defined in an OWNERS file in the root directory of the refs/meta/config branch. This OWNERS file is the parent of the root OWNERS files in all branches. This means if a root OWNERS file disables the inheritance of code owners from the parent directories via the set noparent keyword the OWNERS file in the refs/meta/config branch is ignored. Default code owners are not inherited from parent projects. If code owners should be defined for child projects this can be done by setting global code owners.

Using a file extension for OWNERS files

It's possible that projects have a file extension for code owner config files configured. In this case the code owners are defined in OWNERS.<file-extension> files and OWNERS files are ignored. Further details about this are described here.

Cookbook

A cookbook with examples of OWNERS files for various use cases can be found here.

Syntax

An OWNERS file is a set of lines which are order-independent. Each line can be

NOTE: By default the find-owners backend uses FIND_OWNERS_GLOB's as path expressions, but it's possible that a different path expression syntax is configured. All examples on this page assume that FIND_OWNERS_GLOB's are used as path expressions.

File-level rules

File-level rules apply to the entire OWNERS file and should not be repeated.

set noparent

By default, a directory inherits the code owners from its parent directory. e.g. /path/to/OWNERS inherits from /path/OWNERS. Code owners won't be inherited from parent directories if the set noparent keyword is added to an OWNERS file.

For example, the following OWNERS file ignores code owners from the parent directories and defines some local code owners:

  set noparent

  [email protected]
  [email protected]

Access grants

Access grants assign code ownerships to users.

user emails

In a typical OWNERS file, many lines are user emails. These user emails grant code ownership to the users that own these emails in Gerrit.

For example, the following OWNERS file lists a few different users who are code owners:

  [email protected]
  [email protected]
  [email protected]


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

User emails that are added to OWNERS files must be resolvable in Gerrit. This means:

  • there must be an active Gerrit account that has this email assigned, which is only the case if the user logged in at least once into the Gerrit WebUI (or if an administrator registered the user programatically)
  • the email is not ambiguous (the email belongs to exactly one active Gerrit account)
  • the email has an allowed email domain (see allowed email domain configuration).

NOTE: Non-resolvable code owners in submitted code owner configuration files are ignored.

NOTE: In Gerrit the visibility of users is controlled via the accounts.visibility configuration. This means not every user may be able to see every other user. For code owners this means:

  • you can only add users as code owner that are visible to you
  • by adding a user as code owner you expose the existence of this user to everyone who can read the OWNERS file
  • the code owner suggestion only suggests code owners that are visible to the calling user, this means if the OWNERS file contains code owners that are not visible to the calling user, they are omitted from the suggestion
  • code owners which are referenced by secondary email cannot be resolved for most users, this is because secondary emails of users are only visible to users that have the Modify Account global capability assigned in Gerrit, which is normally only granted to administrators

NOTE: Via configuration it is possible to limit the email domains that are allowed for code owners. User emails that have an email domain that is not allowed cannot be added as code owner, and are ignored if they exist.

All users

Using '*' as user email assigns the code ownership to all registered users, which 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).

file keyword

A file:<path-to-owners-file> line includes rules from another OWNERS file. The path may be either a relative path (e.g. ../sibling/OWNERS) or an absolute path (e.g. /build/OWNERS). The specified path must include the name of the referenced code owner config file (e.g. OWNERS).

  file:/build/OWNERS
  [email protected]
  [email protected]


Many projects prefer to use the relative form for nearby OWNERS files. Absolute paths are recommended for distant paths, but also to make it easier to copy or integrate the line between multiple OWNERS files.

The file that is referenced by the file keyword must be a code owner config file. It's not possible to import arbitrary files.

It's also possible to reference code owner config files from other projects or branches (only within the same host):

  • file:<project>:<path-to-owners-file>: Loads the <path-to-owners-file> code owner config file from the specified project. The code owner config file is loaded from the same branch that also contains the importing OWNERS file (e.g. if the importing OWNERS file is in the master branch then <path-to-owners-file> will be imported from the master branch of the specified project. Example: file:foo/bar/baz:/path/to/OWNERS
  • file:<project>:<branch>:<path-to-owners-file>: Loads the <path-to-owners-file> code owner config file from the specified branch of the specified project. The branch can be specified as full ref name (e.g. refs/heads/master) or as short branch name (e.g. master). Example: file:foo/bar/baz:master:/path/to/OWNERS

If referenced OWNERS files do not exists, they are silently ignored when code owners are resolved, but trying to add references to non-existing OWNERS file will be rejected on upload/submit. Being ignored means that the @PLUGIN@ doesn't bail out with an error when code owners are resolved, but the import of non-resolvable OWNERS files prevents fallback code owners from being applied. The reason for this is that if there is an unresolved import, it is assumed that it was intended to define code owners, e.g. stricter code owners than the fallback code owners, and hence the fallback code owners should not be applied.

When referencing an external OWNERS file via the file keyword, only non-restricted access grants are imported. If they contain imports (via the file or include keyword) they are recursively resolved. This means for the referenced OWNERS files the following things are ignored and not pulled in:

  1. per-file rules
  2. any set noparent line
  3. OWNERS files in parent directories

To also import per-file rules and any set noparent line (1. + 2.) use the include keyword instead.

include keyword

An include <path-to-owners-file> line includes rules from another OWNERS file, similar to the file keyword. The only difference is that using the include keyword also imports per-file rules and any set noparent line from the referenced OWNERS file.

NOTE: In contrast to the file keyword, the include keyword is used without any ':' between the keyword and the file path (e.g. include /path/to/OWNERS).

NOTE: Using the include keyword in combination with a per-file rule is not possible.

Groups

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 or the include keyword. By using a prefix or extension for the OWNERS file it is only interpreted when it is imported into another OWNERS file, but otherwise it has no effect.

Restriction Prefixes

All restriction prefixes should be put at the start of a line, before an access grant.

per-file

A per-file line restricts the given access grant to only apply to a subset of files in the directory:

  per-file <path-exp-1,path-exp-2,...>=<access-grant>


The access grant applies only to the files that are matched by the given path expressions. The path expressions are globs and can match absolute paths or paths relative to the directory of the OWNERS file, but they can only match files in the directory of the OWNERS file and its subdirectories. Multiple path expressions can be specified as a comma-separated list.

In the example below, Jana Roe, John Doe and the code owners that are inherited from parent OWNERS files are code owners of all files that are contained in the directory that contains the OWNERS file. In addition Richard Roe is a code owner of the docs.config file in this directory and all *.md files in this directory and the subdirectories.

  [email protected]
  [email protected]
  per-file docs.config,*[email protected]


NOTE: It's important to not include additional spaces in per-file lines. E.g. "per-file docs.config, test.config=[email protected]" will make Richard Roe a code owner of the files "docs.config" and " test.config" (pay attention to the leading space), but not for the file "test.config". The correct line to make Richard Roe a code owner of the files "docs.config" and "test.config" would be "per-file docs.config,test.config=[email protected]".

NOTE: 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.

To grant per-file code ownership to more than one user multiple user emails can be specified as comma-separated list, or an external OWNERS file can be referenced via the file keyword. Alternatively the per-file line can be repeated multiple times.

  [email protected]
  [email protected]
  per-file docs.config,*[email protected],[email protected]
  per-file docs.config,*.md=file:/build/OWNERS


When referencing an external OWNERS file via the file keyword, only non-restricted access grants are imported. This means per-file rules from the referenced OWNERS file are not pulled in and also any set noparent line in the referenced OWNERS file is ignored, but recursive imports are being resolved.

Using the include keyword in combination with a per-file rule is not possible.

It's also possible to combine set noparent with per-file rules to prevent access by non-per-file owners from the current directory as well as from parent directories.

In the example below, Richard Roe is the only code owner of the docs.config file in this directory and all *.md files in this directory and the subdirectories. All other files in this directory and its subdirectories are owned by Jana Roe, John Doe and the code owners that are inherited from parent directories.

  [email protected]
  [email protected]
  per-file docs.config,*.md=set noparent
  per-file docs.config,*[email protected]

Annotations

Lines that assign code ownership to users (email lines and per-file lines) can be annotated. Annotations have the format #{ANNOTATION_NAME} and can appear at the end of the line. E.g.:

  [email protected] #{LAST_RESORT_SUGGESTION}
  per-file docs.config,*[email protected] #{LAST_RESORT_SUGGESTION}


Annotations can be mixed with comments that can appear before and after annotations, E.g.:

  [email protected] # foo bar #{LAST_RESORT_SUGGESTION} baz


The following annotations are supported:

  • LAST_RESORT_SUGGESTION: Code owners with this annotation are omitted when suggesting code owners, except if dropping these code owners would make the suggestion result empty or if these code owners are already reviewers of the change. If code ownership is assigned to the same code owner through multiple relevant access grants in the same code owner config file or in other relevant code owner config files the code owner gets omitted from the suggestion if it has the LAST_RESORT_SUGGESTION set on any of the access grants.

Unknown annotations are silently ignored.

NOTE: If a line that assigns code ownership to multiple users has an annotation, this annotation applies to all these users. E.g. if an annotation is set for the all users wildcard (aka *) it applies to all users.

NOTE: Only email lines and per-file lines that assign code ownership directly to users support annotations, for other lines (e.g. file lines, include lines and per-file lines that reference other OWNERS files via the file keyword) annotations are interpreted as comments and are silently ignored.

Comments

The '#' character indicates the beginning of a comment. Arbitrary text may be added in comments.

Comments can appear at the end of any line or consume the whole line (a line starting with '#', # <comment-test).

Comments are not interpreted by the code-owners plugin and are intended for human readers of the OWNERS files. However some projects/teams may have own tooling that uses comments to store additional information in OWNERS files.

Back to @PLUGIN@ documentation index

Part of Gerrit Code Review