Here we show first an example use case followed by more details of each configuration rule and variable.
The find-owners plugin is used in Android Open Source Project (AOSP). Here is one AOSP change that modified multiple OWNERS files. If you sign in to the AOSP Gerrit server, you can see and click the [FIND OWNERS]
button and it will pop up a window with owners of the changed files.
The AOSP Gerrit server and projects are configured with the following steps:
Enable the plugin in Gerrit configuration file gerrit.config:
[plugin "find-owners"] enable = true maxCacheAge = 30 maxCacheSize = 2000 alwaysShowButton = true
[FIND OWNERS]
button.Enable the upload validator in project.config of the All-Projects project, in the refs/meta/config branch:
[plugin "find-owners"] rejectErrorInOwners = true
Optionally redefine OWNERS file name in project.config of some projects, in the refs/meta/config branch:
[plugin "find-owners"] ownersFileName = OWNERS.android
Call the submit filters in rules.pl of All-Projects, in the refs/meta/config branch:
% Special projects, branches, user accounts can opt out owners review. % To disable all find_owners rules, add opt_out_find_owners :- true. opt_out_find_owners :- gerrit:change_branch('refs/heads/pie-gsi'). % Special projects, branches, user accounts can opt in owners review. % To default to find_owners rules, add opt_in_find_owners :- true. opt_in_find_owners :- true. % If opt_out_find_owners is true, remove all 'Owner-Review-Vote' label; % else if opt_in_find_owners is true, call find_owners:submit_filter; % else default to no find_owners filter. check_find_owners(In, Out) :- ( opt_out_find_owners -> find_owners:remove_need_label(In, Temp) ; opt_in_find_owners -> find_owners:submit_filter(In, Temp) ; In = Temp ), Temp =.. [submit | A], change_find_owners_labels(A, B), Out =.. [submit | B]. submit_filter(In, Out) :- In =.. [submit | A], check_drno_review(A, B), check_api_review(B, C), check_qualcomm_review(C, D), Temp =.. [submit | D], check_find_owners(Temp, Out). % Remove useless label('Owner-Approved',_) after final filter. % Change optional label('Owner-Review-Vote', may(_)) to % label('Owner-Review-Vote', need(_)) to hide the Submit button. change_find_owners_labels([], []). change_find_owners_labels([H | T], R) :- H = label('Owner-Approved', _), !, change_find_owners_labels(T, R). change_find_owners_labels([H1 | T], [H2 | R]) :- H1 = label('Owner-Review-Vote', may(_)), !, H2 = label('Owner-Review-Vote', need(_)), change_find_owners_labels(T, R). change_find_owners_labels([H | T], [H | R]) :- change_find_owners_labels(T, R).
submit_rule
and submit_filter
To enforce the owner-approval-before-submit rule, this plugin provides find_owners:submit_rule/1
and find_owners:submit_filter/2
predicates for Gerrit projects.
If a Gerrit project wants to enforce this owner-approval policy, it can add a submit_rule
to the rules.pl
file in refs/meta/config
like this:
submit_rule(S) :- find_owners:submit_rule(S).
If many projects need this owner-approval policy, each of them can have a submit_rule
defined, or we can simply define a submit_filter
in their common parent project's rules.pl
file like this:
submit_filter(In, Out) :- find_owners:submit_filter(In, Out).
By default the find_owners:submit_rule
calls gerrit:default_submit
, and the find_owners:submit_filter
passes In
to Out
. They add special labels to the output to indicate if owner approval is needed or missing.
label('Owner-Approved', may(_))
is added. This is an optional requirement that does not affect a change's submittability.label('Owner-Approved', ok(user(1)))
is added.label('Owner-Review-Vote', may(_))
is added. This will show the label but not disable the Submit button. When a user clicks on the Submit button, a window will pop up and ask the user to (1) add missing owners to the reviewers list and/or ask for owner's +1 Code-Review votes, or (2) add Exempt-From-Owner-Approval:
to the commit message. The [FIND OWNERS]
button is useful in this situation to find the missing owners or +1 votes of any changed files.When label('Owner-Approved', may(_))
is added to the submit rule output, Gerrit displays a grey ‘Owner-Approved’ label. To avoid confusion, this may(_)
state label could be removed by the submit_filter
of the root level All-Projects
. Special automerge processes could create changes that do not need either Code-Review vote or owner approval. Such special conditions can also be handled in the submit_filter
of All-Projects
.
A change can be declared as exempt from owner approval in the submit message, with a special keyword Exempt-From-Owner-Approval:
followed by some explanation.
When find_owners:submit_rule(S)
or find_owners:submit_filter(In,Out)
are applied, the default requirement is +1 Code-Review vote from at least one owner of every changed file.
This plugin finds owners in default OWNERS files. If a project has already used OWNERS files for other purpose, the “ownersFileName” parameter can be used to change the default.
To check syntax of OWNERS files before they are uploaded, set the following variable in project.config files.
[plugin "find-owners"] rejectErrorInOwners = true
submit_filter/2
The simplest configuration adds to rules.pl
of the root All-Projects
project.
submit_filter(In, Out) :- find_owners:submit_filter(In, Out).
All projects will need at least +1 vote from an owner of every changed files.
submit_rule/2
Add the following to rules.pl
of project P, to change the default and require +2 owner review votes.
submit_rule(S) :- find_owners:submit_rule(S, 2).
All patches to project P will need at least +2 vote from an owner of every changed files.
submit_filter/3
Add the following to rules.pl
of project P, to change the default and require +2 owner review votes.
submit_filter(In, Out) :- find_owners:submit_filter(In, Out, 2).
All child projects of project P will need at least +2 vote from an owner of every changed files.
minOwnerVoteLevel
Add the following to global gerrit.config
or a project's project.config
file, to change the default and require +2 owner review votes.
[plugin "find-owners"] minOwnerVoteLevel = 2
remove_may_label/2
If a change does not need owner approval, the optional greyed out Owner-Approved
label might cause some confusion. To remove that label, we can add the following to rules.pl
of the root All-Projects
project.
submit_filter(In, Out) :- find_owners:submit_filter(In, Temp), find_owners:remove_may_label(Temp, Out).
remove_need_label/2
To make all changes with some special property, e.g., from the auto merger, exempt from owner approval, we can add a special filter to rules.pl
of the root All-Projects
project.
submit_filter(In, Out) :- is_exempt_from_owner_approval(), % define-your-own-rule find_owners:remove_need_label(In, Out).
addDebugMsg
Add the following to global gerrit.config
, to debug the find-owners plugin.
[plugin "find-owners"] addDebugMsg = true
Add the following to global gerrit.config
or a project's project.config
file, to change the default “OWNERS” file name, e.g., to “OWNERS.android”.
[plugin "find-owners"] ownersFileName = OWNERS.android
If ownersFileName is defined the project should have such a specified file at the root directory. Otherwise it would be considered a configuration or Gerrit server error.