Configuration

Table of Contents

Example from AOSP

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:

  1. Enable the plugin in Gerrit configuration file gerrit.config:

    [plugin "find-owners"]
    enable = true
    maxCacheAge = 30
    maxCacheSize = 2000
    • enable = true enables the plugin for all projects.
    • maxCacheAge is the number of seconds owners info will stay in a cache before being refreshed. This reduces repeated access to the same OWNERS files in a repository. If it is set to 0 (default), there will be no cache.
    • maxCacheSize limits the number of owners info stored in the cache to reduce memory footprint.

  2. Enable the upload validator in project.config of the All-Projects project, in the refs/meta/config branch:

    [plugin "find-owners"]
    rejectErrorInOwners = true
    • The upload validator checks basic syntax of uploaded OWNERS files. It also checks if all email addresses used in OWNERS files belong to active Gerrit accounts.
    • All other Gerrit projects inherit from All-Projects, so they have the same enabled upload validator.

  3. Optionally redefine OWNERS file name in project.config of some projects, in the refs/meta/config branch:

    [plugin "find-owners"]
    ownersFileName = OWNERS.android
    • The AOSP platform/external/v8 project keeps a copy of upstream source from https://github.com/v8/v8.
    • The v8 upstream source already has its OWNERS files that do not work with AOSP Gerrit, because the Email addresses in those files are not all active developers for AOSP. So we need to use different owners files, with the OWNERS.android file name.

  4. 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).
    • With predefined Gerrit Prolog Facts, any project, branch, or user can be matched and added to the opt_out_find_owners or opt_in_find_owners rules.
    • If the submit_filter output contains label('Owner-Review-Vote', need(_)), the Gerrit change cannot be submitted.
    • For a simpler configuration without opt-out projects, just call find_owners:submit_filter and change_find_owners_labels.

Global vs Project Variables

In the AOSP example, we saw that some variables are defined in global gerrit.config and some are defined in project-specific project.config files. The Prolog submit rules are defined in the rules.pl files of each project. The following is a summary of all user-configurable variables for this plugin.

  • Global variables must be defined in gerrit.config:

    • enabled should be true to enable this plugin. Note that this variable enables the UI [FIND OWNERS] button but not yet the submit rules and upload validator.

    • maxCacheAge has default value 0, meaning no cache. All CLs for one Gerrit site share the same cache of owners info, which will stay in cache for up to maxCacheAge seconds.

    • maxCacheSize has default value 1000. When maxCacheAge is non-zero, up to maxCacheSize owner info objects will be stored in the cache.

    • minOwnerVoteLevel has default value 1. It means that when owner approval check is enabled, every changed file needs at least one owner‘s Code-Review +1 vote. This variable can be defined to 2 to require owner’s +2 Code-Review votes.

    • addDebugMsg has default value false. When it is defined to true, the find-owners REST API will add extra debug messages by default in the returned JSON object.

  • Project variables should be defined in project.config of the All-Projects project and inherited by all other projects, or they can be defined in each individual project.

    • rejectErrorInOwners has default value false. When it is true, an upload-validator will check all new and changed OWNERS files and reject the upload when any syntax error is found. If any owner email address in an OWNERS file is not found on the Gerrit site, it will also be considered an error and the upload will be rejected.

    • ownersFileName has default value “OWNERS”. It can be defined to a different name such as “OWNERS.android” if “OWNERS” files already exist for another purpose.

Submit Rules and Filters

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 the refs/meta/config branch 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).

As we saw in the AOSP example, it is much easier to use only the submit_filter in the All-Projects project to check owner approval for all projects. If any project or branch need to opt-out of this check, simple Prolog rules can be defined to skip them, see the opt_out_find_owners rule in the AOSP example.

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', 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. See the change_find_owners_labels rule in the AOSP example.

Exempt from Owner Approval

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.

As shown in the AOSP example, special Prolog rules like opt_out_find_owners can be used to skip find_owners:submit_filter for any project, branch, or user. For example, special automerge processes could create changes that do not need either Code-Review vote or owner approval.

Minimal Owner Code-Review Vote

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. To change this default level, define the plugin minOwnerVoteLevel parameter.

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.

If ownersFileName is defined to something other than OWNERS, the project should have such a specified file at the root directory. Otherwise it would be considered a configuration or Gerrit server error.

OWNERS Upload Validator

To check syntax of OWNERS files before they are uploaded, set the following variable in project.config files.

[plugin "find-owners"]
    rejectErrorInOwners = true

More Prolog Examples

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 Code-Review vote from an owner of every changed files.

Call submit_rule/2

To enabled owner approval requirement only for a project, add the following to its rules.pl. This example also changes the default and require +2 owner Code-Review votes.

submit_rule(S) :- find_owners:submit_rule(S, 2).

Call submit_filter/3

To enabled owner approval requirement only for child projects, add the following to rules.pl. This example explicitly define the required owner Code-Review vote level to 1.

submit_filter(In, Out) :- find_owners:submit_filter(In, Out, 1).

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 call remove_may_label at the end of all find_owners submit filters, in rules.pl of the All-Projects project.

submit_filter(In, Out) :-
  find_owners:submit_filter(In, Temp),
  find_owners:remove_may_label(Temp, Out).

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) :-
  opt_out_find_owners, % define-your-own-rule
  find_owners:remove_need_label(In, Out).

Please review the AOSP example again for more choices to opt-in or opt-out of the find-owners submit filter.