Configuration

The 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.

• If a change does not need owner approval, label('Owner-Approved', may(_)) is added. This is an optional requirement that does not affect a change's submittability.
• If a change needs owner approval, and all changed files have at least one owner voted +1 and no negative vote, label('Owner-Approved', ok(user(1))) is added.
• If a change needs owner approval, but some changed file has no owner +1 vote or has negative owner vote, label('Owner-Review-Vote', need(_)) is added. This will make a change not-submittable. The change author should add missing owners to the reviewers list and/or ask for those owner's +1 Code-Review votes. 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.

Default minimal owner vote level

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.

Default OWNERS file name

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.

Example 0, call 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.

Example 1, call 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.

Example 2, call 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.

Example 3, define 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

Example 4, call 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).

Example 5, call 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).

Example 6, define addDebugMsg

Add the following to global gerrit.config, to debug the find-owners plugin.

[plugin "find-owners"]
    addDebugMsg = true

Example 7, change default OWNERS file name

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