# 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](#codeOwnerApproval) is required to modify the directory or
files under that path.

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

**NOTE:** Being a code owner doesn't grant the user permissions to approve
changes, but permissions to vote on the label that is required as a
[code owner approval](#codeOwnerApproval) must be configured separately. This
means it's possible that a user is a code owner, but misses permissions to apply
code owner approvals.

**NOTE**: Vice versa, having the permissions to vote on the label that is
required as a [code owner approval](#codeOwnerApproval) doesn't make the user a
code owner. Only users that are listed as a code owner in a relevant [code
owner config file](#codeOwnerConfigFiles) (e.g. `OWNERS` file) are considered as
code owner.

## <a id="whyCodeOwners">Why should code owners be used?

Code owners are gatekeepers before a change is submitted, they enforce standards
across the code base, help disseminate knowledge around their specific area of
ownership, ensure there is appropriate code review coverage, and provide timely
reviews.

Enforcing code owner approvals is designed as a code quality feature. Code
owners are defined to ensure someone familiar with the codebase reviews and
approves all changes that are done to the codebase.

By granting a code owner approvel the code owner confirms that the change is
appropriate for the system and is done correctly.

## <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#codeOwnerConfigFiles). 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).

By granting a code owner approvel the code owner confirms that the change is
appropriate for the system and is done correctly.

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](/Documentation/config-labels.html#label_function) independently of
the `@PLUGIN@` plugin).

### <a id="implicitApprovals">
It's possible to [configure implicit
approvals](config.html#codeOwnersEnableImplicitApprovals) for changes/patch-sets
that are owned and uploaded by a code owner. 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 changes 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, i.e. the code owner performs a cherry-pick, the rebased
change has implicit approvals from the code owner, since the code owner is the
change owner and uploader).

**NOTE:** Implicit approvals are applied on changes that are owned by a code
owner, but only if the current patch set was uploaded by the change owner
(change owner == last patch set 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
to be submitted quickly to address an urgent production issue and there is no
time to await all required code owner approvals.

A code owner override is applied by voting on the change. Which label/vote
counts as code owner override depends on the
[configuration](setup-guide.html#configureCodeOwnerOverrides).

**NOTE:** It's possible that overrides are disabled for a project.

## <a id="codeOwnerExemptions">Code owner exemptions

Some changes may be exempted from requiring [code owner
approvals](#codeOwnerApproval):

* changes of [projects](config.html#pluginCodeOwnersDisabled) /
  [branches](config.html#pluginCodeOwnersDisabledBranch) for which the code
  owners functionality has been disabled
* changes that were uploaded by users that are
  [exempted](config.html#pluginCodeOwnersExemptedUser) from requiring code owner
  approvals
* changes that are pure revert, if
  [configured](config.html#pluginCodeOwnersExemptPureReverts)

## <a id="codeOwnerSuggestion">Code owner Suggestion

As a change owner, you need to request code owner approvals for the files that
are modified in the change, so that your change can become submittable. This is
done by selecting a code owner for each of the files and adding them as reviewer
to the change. To help you with this task, Gerrit suggests you suitable code
owners for the files in the change and lets you pick which of them should be
added as reviewers (how this looks in the UI is shown in the
[intro](how-to-use.html#addCodeOwnersAsReviewers) page).

When suggesting code owners for a file, Gerrit filters out code owners that:

* are inactive
* are not visible to you (according to
[accounts.visibility](../../../Documentation/config-gerrit.html#accounts.visibility)
setting),
* are referenced by non-visible secondary emails
* are not resolvable (emails for which no Gerrit account exists)
* are ambiguous (the same email is assigned to multiple accounts)
* are referenced by an email with a disallowed domain (see
  [allowedEmailDomain configuration](config.html#pluginCodeOwnersAllowedEmailDomain))
* do not have read access to the destination branch of the change
* are service users (members of the `Service Users` group)
* code owners that are annotated with
  [LAST_RESORT_SUGGESTION](backend-find-owners.html#lastResortSuggestion),
  except if dropping these code owners would make the suggestion result empty

The suggested code owners are sorted by score, so that the best suitable code
owners appear first. To compute the score multiple [scoring
factors](rest-api.html#scoringFactors) are taken into account, e.g. the distance
of the [code owner config file](#codeOwnerConfigFiles) that defines the code
owner to the path for which code owners are listed (the lower the distance the
better the code owner).

**NOTE:** Fallback code owners, if
[configured](config.html#pluginCodeOwnersFallbackCodeOwners), are not included
in the suggestion.

## <a id="noCodeOwnersDefined">How to submit changes with files that have no code owners?

If the code owners functionality is enabled, all touched files require an
approval from a code owner. If files are touched for which no code owners are
defined, the change can only be submitted with an approval of a fallback code
owner (if [configured](config.html#pluginCodeOwnersFallbackCodeOwners)) or with
a [code owner override](#codeOwnerOverride). Please note that fallback code
owners are not included in the [code owner suggestion](#codeOwnerSuggestion).

## <a id="renames">Renames

A rename is treated as a deletion at the old path and a creation at the new
path. This is why for files that are renamed, Gerrit requires a code owner
approval for the old and the new path of the files (also see [code owner
approval](#codeOwnerApproval) section).

When files/folders get renamed, their code owner configuration should stay
intact. Renaming a file/folder should normally not result in a situation where
the code owner configuration for this file/folder no longer applies, because it
was renamed.

Mostly this is not a problem because [code owner config
files](#codeOwnerConfigFiles) are stored inside the folders to which they apply.
This means, if a folder gets renamed, the code owner config files in it still
apply.

However if a file/folder is renamed for which specific code owners are defined
via [path expressions](path-expressions.html), it is possible that the code
ownership changes. For example, this can happen if the old name is matched by
a path expression that makes user A a code owner, but the new name is only
matched by another path expression that makes user B a code owner. E.g. '*.md'
is owned by user A, '*.txt' is owned by user B and 'config.md' is renamed to
'config.txt'. In this case it is the responsibility of the author doing the
rename and the current code owners to ensure that the file/folder has the proper
code owners at the new path. This is also the reason why [matching subfolders
via path expressions is
discouraged](backend-find-owners.html#doNotUsePathExpressionsForSubdirectories).

## <a id="mergeCommits">Merge commits

By default, changes for merge commits require code owner approvals for all files
that differ between the merge commit that is being reviewed and the tip of the
destination branch (the first parent commit). This includes all files that have
been touched in other branches and that are now being integrated into the
destination branch (regardless of whether there was a conflict resolution or
whether the auto-merge succeeded without conflicts). The overall approval value
for the automatically merged files is shown on the `Auto Merge` base along with
a button to switch to the `Parent 1` base which shows the files individually.

By [configuration](config.html#codeOwnersMergeCommitStrategy) it is possible,
that changes for merge commits only require code owner approvals for files that
differ between the merge commit that is being reviewed and the `Auto Merge`. In
this case, code owners only need to approve the files for which a conflict
resolution was done. These are the files that are shown in the change screen
when `Auto Merge` is selected as base. Using this configuration makes sense if
all branches require code owner approvals and the code owners of all branches
are trusted, as it prevents that code owners need to approve the same changes
multiple times, but for different branches.

## <a id="codeOwnersSubmitRule">Code Owners Submit Rule

The logic that checks whether a change has sufficient [code owner
approvals](#codeOwnerApproval) to be submitted is implemented in the code owners
submit rule. If the code owners submit rule finds that code owner approvals are
missing, the submission of the change is blocked. In this case it's possible to
use a [code owner override](#codeOwnerOverride) to unblock the change
submission.

**NOTE:** Besides the code owners submit rule there may be further submit rules
that block the change submission for other reasons that are not related to code
owners. E.g. configured [label
functions](../../../Documentation/config-labels.html#label_function) are
completely orthogonal to code owner approvals. If, for example, `Code-Review+1`
votes are required as code owner approval, but the `Code-Review` label has the
function `MaxWithBlock` the change submission is still blocked if a max approval
(aka `Code-Review+2`) is missing or if a veto vote (aka `Code-Review-2`) is
present.

**NOTE:** Gerrit submit rules are executed on submit and when change details are
loaded, e.g. when loading the change screen (to know whether the submit button
should be enabled). In addition, submit rules are executed on every change
update because the result of running submit rules is stored as submit records in
the change index. This makes the submit records available when querying changes
(without needing to run the submit rules for every change in the result which
would be too expensive). For code owners the submit records that are stored in
the index can become stale for 2 reasons: 1. [code owner config
files](#codeOwnerConfigFiles) are changed after the change has been indexed
(e.g. new code owners are added), 2. [if the code owners plugin configuration
was changed in a way that affected the result of the code owners submit
rule](config.html#staleIndexOnConfigChanges). Callers of change queries should
be aware of this.

---

Back to [@PLUGIN@ documentation index](index.html)

Part of [Gerrit Code Review](../../../Documentation/index.html)