<commit_before># User Guide

The `@PLUGIN@` plugin allows to define [code owners](#codeOwners) for
directories and files and requires their [approval](#codeOwnerApproval) for
changes that touch these files.

This user guide explains the functionality of the `@PLUGIN@` plugin. For a
walkthrough of the UI please refer to the [intro](how-to-use.html) page.

**TIP:** You may also want to check out the [presentation about code
owners](https://docs.google.com/presentation/d/1DupBnGr3apIx-jzxi9cHzSgkI-2c1ouGu1teQ4khSfc)
from the [Gerrit Contributor Summit
2020](https://docs.google.com/document/d/1WauJfNxracjBK3PxuVnwNIppESGMBtZwxMYjxxeDN6M).

**NOTE:** How to setup the code owners functionality is explained in the
[setup guide](setup-guide.html).

## <a id="codeOwners">What are code owners?

A code owner is a user that is configured as owner of a path (directory or file)
and whose approval is required to modify the path or files under that path.

Who is a code owner of a path is controlled via [code owner config
files](#codeOwnerConfigFiles).

## <a id="codeOwnerConfigFiles">Code owner config files

Code owner config files are stored in the source tree of the repository and
define the [code owners](#codeOwners) for a path.

In which files code owners are defined and which syntax is used depends on the
configured [code owner backend](backends.html). Example: if the
[find-owners](backend-find-owners.html) backend is used, code owners are defined
in [OWNERS](backend-find-owners.html#syntax) files.

To create/edit code owner config files, clone the repository, edit the code
owner config files locally and then push the new commit to the remote repository
in Gerrit. This the same as creating/editing any other source files.

On push, Gerrit [validates](validation.html) any code owner config file that is
touched by the new commits, unless [the validation for received commits is
disabled](config.html#codeOwnersEnableValidationOnCommitReceived).
If the validation is enabled, commits that make code owner config files invalid
are rejected.

**NOTE:** There is no dedicated editor for code owner config files in the Gerrit
UI.

**NOTE:** It is the responsibility of the project owners to maintain the code
owner config files (e.g. take care to remove code owners that leave the team).

## <a id="codeOwnerApproval">Code owner approval

For a change to be submittable Gerrit requires that all files that are touched
in the change are approved by a code owner.

Code owners apply their approval by voting on the change. By default, voting
with `Code-Review+1` counts as code owner approval, but it's possible that the
host administrators or the project owners have [configured a different label/vote
that is required as code owner approval](setup-guide.html#configureCodeOwnerApproval).

The code owner check for a file is satisfied as soon as one of its code owners
grants the code owner approval. Negative votes from other code owners do not
block the submission (unless it's a veto vote which is configured independently
of the `@PLUGIN@` plugin).

It's possible to configure that for changes/patch-sets that are uploaded by a
code owner an implict code owner approval from the uploader is assumed. In this
case, if a code owner only touches files that they own, no approval from other
code owners is required. If this is configured, it is important that code owners
are aware of their implicit approval when they upload new patch sets for other
users (e.g. if a contributor pushes a change to a wrong branch and a code owner
helps them to get it rebased onto the correct branch, the rebased change has
implicit approvals from the code owner, since the code owner is the uploader).

For files that are [renamed/moved](#renames) Gerrit requires a code owner
approval for the old and the new path of the files.

If code owner approvals are missing, it is possible to submit the change with a
[code owner override](#codeOwnerOverride), but this should only be done in
exceptional cases.

**NOTE:** It is possible that users are code owners, but miss permissions to
vote on the required label. This is a configuration issue that should be
reported to the project owners (who should either
[grant the permission](setup-guide.html#grantCodeOwnerPermissions) or remove
the code owner).

**NOTE:** It's possible that the change submission is still blocked after all
necessary code owner approvals have been granted. This is the case, if futher
non-code-owner approvals are required and missing, or if further non-code-owner
submit requirements are not fulfilled yet.

**NOTE:** Whether code owner approvals are sticky across patch sets depends on
the definition of the required label. If the label definition has [copy
rules](../../../Documentation/config-labels.html#label_copyAnyScore) enabled so
that votes are sticky across patch sets, then also the code owner approvals
which are based on these votes will be sticky.

**NOTE:** Whether code owners can approve their own changes depends of the
definition of the required label. If the label definition has
[ignoreSelfApproval](../../../Documentation/config-labels.html#label_ignoreSelfApproval)
enabled, code owner approvals of the patch set uploader are ignored.

## <a id="codeOwnerOverride">Code owner override

Usually some privileged users, such as sheriffs, are allowed to override the
code owner approval check to make changes submittable, even if code owner
approvals for some or all files are missing.

Overrides are intended to be used in emergency cases only. What qualifies as an
emergency depends on the project. Usually overrides are used when changes need<commit_msg>Document that code owner approvals always apply to all files in the change<commit_after># User Guide

The `@PLUGIN@` plugin allows to define [code owners](#codeOwners) for
directories and files and requires their [approval](#codeOwnerApproval) for
changes that touch these files.

This user guide explains the functionality of the `@PLUGIN@` plugin. For a
walkthrough of the UI please refer to the [intro](how-to-use.html) page.

**TIP:** You may also want to check out the [presentation about code
owners](https://docs.google.com/presentation/d/1DupBnGr3apIx-jzxi9cHzSgkI-2c1ouGu1teQ4khSfc)
from the [Gerrit Contributor Summit
2020](https://docs.google.com/document/d/1WauJfNxracjBK3PxuVnwNIppESGMBtZwxMYjxxeDN6M).

**NOTE:** How to setup the code owners functionality is explained in the
[setup guide](setup-guide.html).

## <a id="codeOwners">What are code owners?

A code owner is a user that is configured as owner of a path (directory or file)
and whose approval is required to modify the path or files under that path.

Who is a code owner of a path is controlled via [code owner config
files](#codeOwnerConfigFiles).

## <a id="codeOwnerConfigFiles">Code owner config files

Code owner config files are stored in the source tree of the repository and
define the [code owners](#codeOwners) for a path.

In which files code owners are defined and which syntax is used depends on the
configured [code owner backend](backends.html). Example: if the
[find-owners](backend-find-owners.html) backend is used, code owners are defined
in [OWNERS](backend-find-owners.html#syntax) files.

To create/edit code owner config files, clone the repository, edit the code
owner config files locally and then push the new commit to the remote repository
in Gerrit. This the same as creating/editing any other source files.

On push, Gerrit [validates](validation.html) any code owner config file that is
touched by the new commits, unless [the validation for received commits is
disabled](config.html#codeOwnersEnableValidationOnCommitReceived).
If the validation is enabled, commits that make code owner config files invalid
are rejected.

**NOTE:** There is no dedicated editor for code owner config files in the Gerrit
UI.

**NOTE:** It is the responsibility of the project owners to maintain the code
owner config files (e.g. take care to remove code owners that leave the team).

## <a id="codeOwnerApproval">Code owner approval

For a change to be submittable Gerrit requires that all files that are touched
in the change are approved by a code owner.

Code owners apply their approval by voting on the change. By default, voting
with `Code-Review+1` counts as code owner approval, but it's possible that the
host administrators or the project owners have [configured a different label/vote
that is required as code owner approval](setup-guide.html#configureCodeOwnerApproval).

The code owner check for a file is satisfied as soon as one of its code owners
grants the code owner approval. Negative votes from other code owners do not
block the submission (unless it's a veto vote which is configured independently
of the `@PLUGIN@` plugin).

It's possible to configure that for changes/patch-sets that are uploaded by a
code owner an implict code owner approval from the uploader is assumed. In this
case, if a code owner only touches files that they own, no approval from other
code owners is required. If this is configured, it is important that code owners
are aware of their implicit approval when they upload new patch sets for other
users (e.g. if a contributor pushes a change to a wrong branch and a code owner
helps them to get it rebased onto the correct branch, the rebased change has
implicit approvals from the code owner, since the code owner is the uploader).

For files that are [renamed/moved](#renames) Gerrit requires a code owner
approval for the old and the new path of the files.

If code owner approvals are missing, it is possible to submit the change with a
[code owner override](#codeOwnerOverride), but this should only be done in
exceptional cases.

**NOTE:** It is possible that users are code owners, but miss permissions to
vote on the required label. This is a configuration issue that should be
reported to the project owners (who should either
[grant the permission](setup-guide.html#grantCodeOwnerPermissions) or remove
the code owner).

**NOTE:** It's possible that the change submission is still blocked after all
necessary code owner approvals have been granted. This is the case, if futher
non-code-owner approvals are required and missing, or if further non-code-owner
submit requirements are not fulfilled yet.

**NOTE:** Whether code owner approvals are sticky across patch sets depends on
the definition of the required label. If the label definition has [copy
rules](../../../Documentation/config-labels.html#label_copyAnyScore) enabled so
that votes are sticky across patch sets, then also the code owner approvals
which are based on these votes will be sticky.

**NOTE:** Whether code owners can approve their own changes depends of the
definition of the required label. If the label definition has
[ignoreSelfApproval](../../../Documentation/config-labels.html#label_ignoreSelfApproval)
enabled, code owner approvals of the patch set uploader are ignored.

**NOTE:** Code owner approvals are always applied on the whole change / patch
set and count for all files in the change / patch set. It is not possible to
approve individual files only. This means code owners should always review all
files in the change / patch set before applying their approval. E.g. it is
discouraged to only review the owned files, since the set of owned files can
change if `OWNERS` files in the destination branch are changed after the
approval has been applied.

## <a id="codeOwnerOverride">Code owner override

Usually some privileged users, such as sheriffs, are allowed to override the
code owner approval check to make changes submittable, even if code owner
approvals for some or all files are missing.

Overrides are intended to be used in emergency cases only. What qualifies as an
emergency depends on the project. Usually overrides are used when changes need
{'fraction_non_alphanumeric': 0.05668187193782734, 'fraction_numerical': 0.002534211860111505, 'mean_word_length': 4.869608329201784, 'pattern_counts': {'":': 0, '<': 11, '<?xml version=': 0, '>': 11, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '655788', 'n_tokens_mistral': 3077, 'n_tokens_neox': 2959, 'n_words': 1718}