The code-owners
plugin provides support for code owners in Gerrit and is replacing the find-owners
plugin.
For projects that used code owners with the find-owners
plugin before, the existing OWNERS
files continue to work and the only major difference is that the code-owners
plugin comes with a new UI for selecting code owners and showing the code owner status.
The code-owners
plugin is an open-source plugin and is maintained by the Gerrit team at Google.
This document focuses on the workflows in the UI. Further information can be found in the backend user guide.
You don’t need to do anything as the plugin is enabled by the host admin.
The code-owners
plugin is only supported for the Gerrit version that is currently developed in master. The first Gerrit release that supports the code-owners
plugin is Gerrit 3.3.0.
Before installing/enabling the plugin, or enabling the code owners functionality for further projects, it is important that the plugin is correctly configured. The required configuration is described in the plugin setup guide.
Report a bug or send feedback using this Monorail template. You can also report a bug through the bug icon in the reply dialog next to the HIDE OWNERS
/ SUGGEST OWNERS
button.
A code owner is a user whose approval is required to modify files under a certain path. Who is a code owner of a path is controlled via OWNERS
files that are checked into the repository. For submitting a change Gerrit requires that all files that were touched in the change are approved by a code owner. Code owners usually apply their approval by voting with “Code-Review+1” on the change. Their approval is to confirm that “This change is appropriate for our system and belongs in this directory."
Owners are gatekeepers before a CL is submitted, they enforce standards across the code base, help disseminate knowledge around their specific area of ownership, ensure their is appropriate code review coverage, and provide timely reviews. Code owners is designed as a code quality feature to ensure someone familiar with the code base reviews any changes to the codebase or a subset of the codebase they are the Owner of, by making sure the change is appropriate for the system.
code-owners
plugin?Code owners in Gerrit will be supported by a new code-owners
plugin which is developed as an open-source plugin and maintained by the Gerrit team at Google.
The code-owners
plugin supports:
The plugin provides suggestions of owners for the directory or files that you are modifying in your change based on a score. It also informs you at a glance about the status of code owners for the change and the status of code owners per file.
The code-owners
plugin suggests a maximum of 5 closest code owners based on their score. The code owner score is calculated based on the distance of code owners to the files.
If you have used code owners via the find-owners
plugin before, your code owners are already defined in OWNERS
files and you don’t need to do anything since the new code-owners
plugin just reads the existing OWNERS
files.
If you haven’t used code owners before, you can now define code owners 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).
The syntax of OWNERS
file is explained in the backend documentation and examples can be found in the cookbook.
The code-owners plugin does not support an editor to create and edit OWNERS
files from the UI. OWNERS
files must be created and edited manually in the local repository and then be pushed to the remote repository, the same way as any other source file.
SUGGEST OWNERS
next to the Code-Owners
submit requirement.SEND
to notify the code owners you selected on your change.Once a file has received an approval vote by the code owner, the file disappears from the file list in the reply dialog. This lets you focus on the files that are not yet assigned to a code owner or are pending approval.
There are 3 possible reasons for encountering a “Not found” text:
No owners were defined for these files. Reason: This could be due to missing OWNERS
defined for these files.
None of the code owners of these files are visible. Reason: The code owners accounts are not visible to you.
Code owners defined for these files are invalid. Reason: The emails cannot be resolved.
For these 3 cases, we advise you to:
Renamed files (new path) will have a “Renamed” chip attached to them. A renamed file will be considered as approved only if both old path/name and new path/name are approved.
This status is informing you about a failed API call. Refresh the page to recover from this error.
In case of a large change containing a large number of files (hundreds or even thousands), it will take some time to fetch all suggested code owners. In the reply dialog, the plugin will show the overall status of the fetching and results as soon as it has results together with the loading indicator. The loading will disappear until all files finished fetching, failed files will be grouped into a single group.
The fetching of suggested code owners should not block the reply itself. So you still can select from suggestions even when not all files are finished and sent for reviewing.
In the change page, you can get an overview of the code owner statuses.
If applicable, the code owner status is displayed:
Code-Owners
submit requirementCode-Owners
submit requirementThe Code-Owners
submit requirement is providing an overview about the code owner status at a glance.
Missing code owner approval
The change is missing a reviewer that can grant the code owner approval.
Pending code owner approval
Approved by code owner
Each file in your change was approved by at least one code owner. It's not required that all code owners approve a change.
Additionally, the code-owners
plugin provides a more detailed overview of code owner status per file in the change with 3 statuses and you can hover over the icon to display a tooltip.
Missing code owner approval
A code owner of this file is missing as a reviewer to the change.
Pending code owner approval
A code owner of this file has been added to the change but have not voted yet.
Approved by code owner
A code owner of this file has approved the change. You can also see this icon if you are a code owner of the file as in this case the file is implicitly approved by you.
Failed to fetch status icon
This status is informing you about a failed API call. Refresh the page to recover from this error.
When you own all the files in your change, the code-owners
plugin will:
Code-Owners
submit requirementThe Owners-Override
label is votable by a user with certain permissions (e.g. sheriff). The Owner-Override
label will show in the reply dialog and you can vote on it if you have certain permissions.