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 its rules.pl
file 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