src/main/resources/Documentation/config.md - plugins/owners - Git at Google

 @PLUGIN@ configuration
 ======================

 ## Global configuration

 The global plugin configuration is read from the `$GERRIT_SITE/etc/owners.config`
 and is applied across all projects in Gerrit.

 owners.disable.branch
 :   List of branches regex where the resolution of owners is disabled.

     Example:

     ```
     [owners "disable"]
       branch = refs/meta/config
       branch = refs/heads/sandboxes.*
     ```

 owners.expandGroups
 :   Expand owners and groups into account ids. If set to `false` all owners are left untouched,
 apart from e-mail
 addresses which have the domain dropped. Defaults to `true`.

     Example:

     ```
     [owners]
       expandGroups = false
     ```

 owners.label
 :   Global override for the label and score, separated by a comma, to use by
 the owners of changes for approving them. When defined, it overrides any
 other label definition set by the OWNERS at any level in any project.

 > **NOTE:** Compulsory when the selected label's function is NoBlock/NoOp.

     Example:

     ```
     [owners]
       label = Code-Review, 1
     ```

 <a name="owners.enableSubmitRequirement">owners.enableSubmitRequirement</a>
 :   If set to `true` the approvals are evaluated through the owners plugin
 default submit requirement, named "Code-Review-from-Owners", without a need of
 prolog predicate being added to a project or submit requirement configured
 in the `project.config` as it is automatically applied to all projects.
 Defaults to `false`.

     Example:

     ```
     [owners]
       enableSubmitRequirement = true
     ```

     > **Notes:**
     >
     > The `owners.enableSubmitRequirement = true` is a global
     > setting and allows for quick site switch from `prolog` submit rule to
     > plugin's provided submit rule. It is a drop-in replacement therefore,
     > similarly to `prolog` rule, it cannot be overridden by Gerrit. In case
     > when one-step migration is not feasible (e.g. when `prolog` rules need to
     > be slowly phased out or when more control is needed over rule's
     > applicability, submitability or ability to overide) one can configure
     > submit requirement in `project.config` for a certain project (or
     > hierarchy of projects), without turning it on globally, as
     > `approval_owners` predicate is _always_ available.
     >
     > Please also note, that project's `rules.pl` should be removed in this
     > case so that it doesn't interfere with a change evaluation.
     >
     > The minimal configuration looks like below (see
     > [submit requirements documentation](/Documentation/config-submit-requirements.html) for more details):
     > ```
     > [submit-requirement "Owner-Approval"]
     >   description = Files needs to be approved by owners
     >   submittableIf = has:approval_owners
     > ```

 cache."owners.path_owners_entries".memoryLimit
 :   The cache is used to hold the parsed version of `OWNERS` files in the
 repository so that when submit rules are calculated (either through prolog
 or through submit requirements) it is not read over and over again. The
 cache entry gets invalidated when `OWNERS` file branch is updated.
 By default it follows default Gerrit's cache memory limit but it makes
 sense to adjust it as a function of number of project that use the `owners`
 plugin multiplied by average number of active branches (plus 1 for the
 refs/meta/config) and average number of directories (as directory hierarchy
 back to root is checked for the `OWNERS` file existence).
 _Note that in opposite to the previous settings the modification needs to be
 performed in the `$GERRIT_SITE/etc/gerrit.config` file._

     Example

     ```
     [cache "owners.path_owners_entries"]
       memoryLimit = 2048
     ```

 ## Configuration

 Owner approval is determined based on OWNERS files located in the same
 repository on the target branch of the changes uploaded for review.

 The `OWNERS` file has the following YAML structure:

 ```yaml
 inherited: true
 label: Code-Review, 1
 owners:
   - some.email@example.com
   - User Name
   - group/Group of Users
 matchers:
   - suffix: .java
     owners:
         [ ... ]
   - regex: .*/README.*
     owners:
         [ ... ]
   - partial_regex: example
     owners:
         [ ... ]
   - exact: path/to/file.txt
       [...]
 ```

 _NOTE: Be aware to double check that emails and full user names correspond to
 valid registered Gerrit users. When owner user full name or e-mail cannot be
 resolved, a corresponding WARN message is logged on Gerrit error_log and the
 user entry dropped._

 That translates to inheriting owner email address from any parent OWNER files
 and to define 'some.email@example.com' or 'User Name' users as the mandatory
 reviewers for all changes that include modification to those files.

 To specify a group of people instead of naming individual owners, prefix the
 group name or UUID with 'group/'.

 Additional owners can be specified for files selected by other matching
 conditions (matchers section). Matching can be done by file suffix, regex
 (partial or full) and exact string comparison. For exact match, path is
 relative to the root of the repo.

 > **NOTE:** The `generic` matcher is a special type of regex matching that
 > is applied only when none of the other sections are matching. It is
 > used to define fallback rules. The `generic: .*` is the top-level fallback
 > and can be used with other more specific `generic` matchers.

 The plugin analyzes the latest patch set by looking at each file directory and
 building an OWNERS hierarchy. It stops once it finds an OWNERS file that has
 “inherited” set to false (by default it’s true.)

 > **NOTE:** The `label` value (default is `Code-Review`) is taken into
 > consideration only when `owners.enableSubmitRequirement = true`.
 > Owners scores are matched against the label specified in the property in
 > question.
 > The required label's score can be provided (by default label's scores
 > configuration is used) so that owners don't have to be granted with the
 > maximum label's score. Note that only single digit (0..9) is allowed.

 For example, imagine the following tree with a default Gerrit project labels configuration:

 ```
 /OWNERS
 /example/src/main/OWNERS
 /example/src/main/java/com/example/foo/Foo.java
 /example/src/main/resources/config.properties
 /example/src/test/OWNERS
 /example/src/test/java/com/example/foo/FooTest.java
 ```

 If you submit a patch set that changes /example/src/main/java/com/example/foo/Foo.java
 then the plugin will first open /example/src/main/OWNERS and if inherited is set
 to true combine it with the owners listed in /OWNERS.

 If for each patch there is a reviewer who gave a Code-Review +2 then the plugin
 will not add any labels, otherwise, it will add ```label('Code-Review from owners', need(_)).```

 ## Global project OWNERS

 Set a OWNERS file into the project refs/meta/config to define a global set of
 rules applied to every change pushed, regardless of the folder or target branch.

 Example of assigning every configuration files to a specific owner group:

 ```yaml
 matchers:
   - suffix: .config
     owners:
       - Configuration Managers
 ```

 Global refs/meta/config OWNERS configuration is inherited only when the OWNERS file
 contain the 'inherited: true' condition at the top of the file or if they are absent.

 That means that in the absence of any OWNERS file in the target branch, the refs/meta/config
 OWNERS is used as global default.

 If the global project OWNERS has the 'inherited: true', it will check for a global project OWNERS
 in all parent projects up to All-Projects.

 ## auto-owners-approved

 The optional `auto-owners-approved` field controls a specific exception to the default
 `approverin:already-approved-by_owners` copy condition behavior.

 Please refer to the [relevant paragraph](./copy-conditions.md#auto-owners-approved) in
 the [copy-conditions.md](./copy-conditions.md) documentation for details on this.

 ## Example 1 - OWNERS file without matchers

 Given an OWNERS configuration of:

 ```yaml
 inherited: true
 owners:
   - John Doe
   - Doug Smith
 ```

 In this case the owners plugin will assume the default label configuration,`Code-Review
 +2`, as indication of approval.

 To enforce submittability only when the specified owners have approved the
 change, you can then either enable `owners.enableSubmitRequirement = true` in
 your `gerrit.config` or define a submit requirement in your `project.config` that
 uses the `has:approval_owners` in the `submittableIf` section, like so:

 ```
 [submit-requirement "Owner-Approval"]
        description = Files needs to be approved by owners
        submittableIf = has:approval_owners
 ```

 > See [notes](#owners.enableSubmitRequirement) for an example on how to enable
 > submit requirements for a specific project only.

 ## Example 2 - OWNERS file with custom approval label

 Sometimes, teams might wish to use a different label to signal approval from an
 owner, rather than the default `Code-Review +2`. For example, you might wish to
 have a governance team explicitly approving changes but do not wish to necessarily grant
 them code review permissions.

 In this case, we need to grant specific groups with a custom label without
 necessarily giving them Code-Review +2 rights on the entire project.

 Amend the project.config as shown in below and add a new label; then give
 permissions to any registered user:

 ```
 [label "Owner-Approved"]
      function = NoOp
      defaultValue = 0
      copyMinScore = true
      copyAllScoresOnTrivialRebase = true
      value = -1 I don't want this to be merged
      value =  0 No score
      value = +1 Approved
 [access "refs/heads/*"]
      label-Owner-Approved = -1..+1 group Registered Users
 ```

 Given now an OWNERS configuration of:

 ```yaml
 inherited: true
 label: Owner-Approved, 1
 owners:
   - John Doe
   - Doug Smith
 ```

 This will mean that, a change cannot be submitted until 'John Doe' or 'Doug
 Smith' vote +1 on the `Owner-Approved`  label, independently from whomever else
 has provided a `Code-Review +2`.

 > **NOTE:** You can also use `label: Code-Review, 1` as your definition of submittability

 Finally to enable this, you'll need to define a custom submit requirement in
 your `project.config`(as above) or enable `owners.enableSubmitRequirement = true` in your
 `owners.config`

 If you no longer wish to require a `Code-Review +2` and would rather only use
 the custom submit requirement, you have two options:

 - change the definition of the `Code-Review` label in `All-Projects`'s
   `project.config` so that `function = NoOp`.
 - set an `overrideIf` clause in your custom submit requirement definition

 > See [notes](#owners.enableSubmitRequirement) for an example on how to enable
 > submit requirements for a specific project only.

 > See [notes](#label.Label-Name.function) for an example on how to modify
 > label functions, as by default `Code-Review` requires at least one max vote
 > from any user.

 ## Example 3 - Owners based on matchers

 Often the ownership comes from the developer's skills and competencies and
 cannot be purely defined by the project's directory structure.
 For instance, all the files ending with .sql should be owned and signed-off by
 the DBA while all the ones that contain 'Test' should be reviewed by the QA team.

 Given an OWNERS configuration of:

 ```yaml
 inherited: true
 matchers:
   - suffix: .sql
     owners:
       - Mister Dba
   - regex: .*Test.*
     owners:
       - John Bug
       - Matt Free
 ```

 You can then either enable `owners.enableSubmitRequirement = true` in your
 `gerrit.config` or define a submit requirement in your `project.config` that
 uses the `has:approval_owners` in the `applicableIf` section.

 > See [notes](#owners.enableSubmitRequirement) for an example on how to enable
 > submit requirements for a specific project only.
	@PLUGIN@ configuration
	======================

	## Global configuration

	The global plugin configuration is read from the `$GERRIT_SITE/etc/owners.config`
	and is applied across all projects in Gerrit.

	owners.disable.branch
	: List of branches regex where the resolution of owners is disabled.

	Example:

	```
	[owners "disable"]
	branch = refs/meta/config
	branch = refs/heads/sandboxes.*
	```

	owners.expandGroups
	: Expand owners and groups into account ids. If set to `false` all owners are left untouched,
	apart from e-mail
	addresses which have the domain dropped. Defaults to `true`.

	Example:

	```
	[owners]
	expandGroups = false
	```

	owners.label
	: Global override for the label and score, separated by a comma, to use by
	the owners of changes for approving them. When defined, it overrides any
	other label definition set by the OWNERS at any level in any project.

	> NOTE: Compulsory when the selected label's function is NoBlock/NoOp.

	Example:

	```
	[owners]
	label = Code-Review, 1
	```

	<a name="owners.enableSubmitRequirement">owners.enableSubmitRequirement</a>
	: If set to `true` the approvals are evaluated through the owners plugin
	default submit requirement, named "Code-Review-from-Owners", without a need of
	prolog predicate being added to a project or submit requirement configured
	in the `project.config` as it is automatically applied to all projects.
	Defaults to `false`.

	Example:

	```
	[owners]
	enableSubmitRequirement = true
	```

	> Notes:
	>
	> The `owners.enableSubmitRequirement = true` is a global
	> setting and allows for quick site switch from `prolog` submit rule to
	> plugin's provided submit rule. It is a drop-in replacement therefore,
	> similarly to `prolog` rule, it cannot be overridden by Gerrit. In case
	> when one-step migration is not feasible (e.g. when `prolog` rules need to
	> be slowly phased out or when more control is needed over rule's
	> applicability, submitability or ability to overide) one can configure
	> submit requirement in `project.config` for a certain project (or
	> hierarchy of projects), without turning it on globally, as
	> `approval_owners` predicate is _always_ available.
	>
	> Please also note, that project's `rules.pl` should be removed in this
	> case so that it doesn't interfere with a change evaluation.
	>
	> The minimal configuration looks like below (see
	> [submit requirements documentation](/Documentation/config-submit-requirements.html) for more details):
	> ```
	> [submit-requirement "Owner-Approval"]
	> description = Files needs to be approved by owners
	> submittableIf = has:approval_owners
	> ```

	cache."owners.path_owners_entries".memoryLimit
	: The cache is used to hold the parsed version of `OWNERS` files in the
	repository so that when submit rules are calculated (either through prolog
	or through submit requirements) it is not read over and over again. The
	cache entry gets invalidated when `OWNERS` file branch is updated.
	By default it follows default Gerrit's cache memory limit but it makes
	sense to adjust it as a function of number of project that use the `owners`
	plugin multiplied by average number of active branches (plus 1 for the
	refs/meta/config) and average number of directories (as directory hierarchy
	back to root is checked for the `OWNERS` file existence).
	_Note that in opposite to the previous settings the modification needs to be
	performed in the `$GERRIT_SITE/etc/gerrit.config` file._

	Example

	```
	[cache "owners.path_owners_entries"]
	memoryLimit = 2048
	```

	## Configuration

	Owner approval is determined based on OWNERS files located in the same
	repository on the target branch of the changes uploaded for review.

	The `OWNERS` file has the following YAML structure:

	```yaml
	inherited: true
	label: Code-Review, 1
	owners:
	- some.email@example.com
	- User Name
	- group/Group of Users
	matchers:
	- suffix: .java
	owners:
	[ ... ]
	- regex: ./README.
	owners:
	[ ... ]
	- partial_regex: example
	owners:
	[ ... ]
	- exact: path/to/file.txt
	[...]
	```

	_NOTE: Be aware to double check that emails and full user names correspond to
	valid registered Gerrit users. When owner user full name or e-mail cannot be
	resolved, a corresponding WARN message is logged on Gerrit error_log and the
	user entry dropped._

	That translates to inheriting owner email address from any parent OWNER files
	and to define 'some.email@example.com' or 'User Name' users as the mandatory
	reviewers for all changes that include modification to those files.

	To specify a group of people instead of naming individual owners, prefix the
	group name or UUID with 'group/'.

	Additional owners can be specified for files selected by other matching
	conditions (matchers section). Matching can be done by file suffix, regex
	(partial or full) and exact string comparison. For exact match, path is
	relative to the root of the repo.

	> NOTE: The `generic` matcher is a special type of regex matching that
	> is applied only when none of the other sections are matching. It is
	> used to define fallback rules. The `generic: .*` is the top-level fallback
	> and can be used with other more specific `generic` matchers.

	The plugin analyzes the latest patch set by looking at each file directory and
	building an OWNERS hierarchy. It stops once it finds an OWNERS file that has
	“inherited” set to false (by default it’s true.)

	> NOTE: The `label` value (default is `Code-Review`) is taken into
	> consideration only when `owners.enableSubmitRequirement = true`.
	> Owners scores are matched against the label specified in the property in
	> question.
	> The required label's score can be provided (by default label's scores
	> configuration is used) so that owners don't have to be granted with the
	> maximum label's score. Note that only single digit (0..9) is allowed.

	For example, imagine the following tree with a default Gerrit project labels configuration:

	```
	/OWNERS
	/example/src/main/OWNERS
	/example/src/main/java/com/example/foo/Foo.java
	/example/src/main/resources/config.properties
	/example/src/test/OWNERS
	/example/src/test/java/com/example/foo/FooTest.java
	```

	If you submit a patch set that changes /example/src/main/java/com/example/foo/Foo.java
	then the plugin will first open /example/src/main/OWNERS and if inherited is set
	to true combine it with the owners listed in /OWNERS.

	If for each patch there is a reviewer who gave a Code-Review +2 then the plugin
	will not add any labels, otherwise, it will add ```label('Code-Review from owners', need(_)).```

	## Global project OWNERS

	Set a OWNERS file into the project refs/meta/config to define a global set of
	rules applied to every change pushed, regardless of the folder or target branch.

	Example of assigning every configuration files to a specific owner group:

	```yaml
	matchers:
	- suffix: .config
	owners:
	- Configuration Managers
	```

	Global refs/meta/config OWNERS configuration is inherited only when the OWNERS file
	contain the 'inherited: true' condition at the top of the file or if they are absent.

	That means that in the absence of any OWNERS file in the target branch, the refs/meta/config
	OWNERS is used as global default.

	If the global project OWNERS has the 'inherited: true', it will check for a global project OWNERS
	in all parent projects up to All-Projects.

	## auto-owners-approved

	The optional `auto-owners-approved` field controls a specific exception to the default
	`approverin:already-approved-by_owners` copy condition behavior.

	Please refer to the [relevant paragraph](./copy-conditions.md#auto-owners-approved) in
	the [copy-conditions.md](./copy-conditions.md) documentation for details on this.

	## Example 1 - OWNERS file without matchers

	Given an OWNERS configuration of:

	```yaml
	inherited: true
	owners:
	- John Doe
	- Doug Smith
	```

	In this case the owners plugin will assume the default label configuration,`Code-Review
	+2`, as indication of approval.

	To enforce submittability only when the specified owners have approved the
	change, you can then either enable `owners.enableSubmitRequirement = true` in
	your `gerrit.config` or define a submit requirement in your `project.config` that
	uses the `has:approval_owners` in the `submittableIf` section, like so:

	```
	[submit-requirement "Owner-Approval"]
	description = Files needs to be approved by owners
	submittableIf = has:approval_owners
	```

	> See [notes](#owners.enableSubmitRequirement) for an example on how to enable
	> submit requirements for a specific project only.

	## Example 2 - OWNERS file with custom approval label

	Sometimes, teams might wish to use a different label to signal approval from an
	owner, rather than the default `Code-Review +2`. For example, you might wish to
	have a governance team explicitly approving changes but do not wish to necessarily grant
	them code review permissions.

	In this case, we need to grant specific groups with a custom label without
	necessarily giving them Code-Review +2 rights on the entire project.

	Amend the project.config as shown in below and add a new label; then give
	permissions to any registered user:

	```
	[label "Owner-Approved"]
	function = NoOp
	defaultValue = 0
	copyMinScore = true
	copyAllScoresOnTrivialRebase = true
	value = -1 I don't want this to be merged
	value = 0 No score
	value = +1 Approved
	[access "refs/heads/*"]
	label-Owner-Approved = -1..+1 group Registered Users
	```

	Given now an OWNERS configuration of:

	```yaml
	inherited: true
	label: Owner-Approved, 1
	owners:
	- John Doe
	- Doug Smith
	```

	This will mean that, a change cannot be submitted until 'John Doe' or 'Doug
	Smith' vote +1 on the `Owner-Approved` label, independently from whomever else
	has provided a `Code-Review +2`.

	> NOTE: You can also use `label: Code-Review, 1` as your definition of submittability

	Finally to enable this, you'll need to define a custom submit requirement in
	your `project.config`(as above) or enable `owners.enableSubmitRequirement = true` in your
	`owners.config`

	If you no longer wish to require a `Code-Review +2` and would rather only use
	the custom submit requirement, you have two options:

	- change the definition of the `Code-Review` label in `All-Projects`'s
	`project.config` so that `function = NoOp`.
	- set an `overrideIf` clause in your custom submit requirement definition

	> See [notes](#owners.enableSubmitRequirement) for an example on how to enable
	> submit requirements for a specific project only.

	> See [notes](#label.Label-Name.function) for an example on how to modify
	> label functions, as by default `Code-Review` requires at least one max vote
	> from any user.

	## Example 3 - Owners based on matchers

	Often the ownership comes from the developer's skills and competencies and
	cannot be purely defined by the project's directory structure.
	For instance, all the files ending with .sql should be owned and signed-off by
	the DBA while all the ones that contain 'Test' should be reviewed by the QA team.

	Given an OWNERS configuration of:

	```yaml
	inherited: true
	matchers:
	- suffix: .sql
	owners:
	- Mister Dba
	- regex: .Test.
	owners:
	- John Bug
	- Matt Free
	```

	You can then either enable `owners.enableSubmitRequirement = true` in your
	`gerrit.config` or define a submit requirement in your `project.config` that
	uses the `has:approval_owners` in the `applicableIf` section.

	> See [notes](#owners.enableSubmitRequirement) for an example on how to enable
	> submit requirements for a specific project only.