Configuration
=============

## Table of Contents
* [Example from AOSP](#example-from-aosp)
* [Global vs Project Variables](#global-vs-project-variables)
* [Submit Rules and Filters](#submit-rules-and-filters)
* [Exempt from Owner Approval](#exempt-from-owner-approval)
* [Minimal Owner Code-Review Vote](#minimal-owner-code-review-vote)
* [OWNERS File Name](#owners-file-name)
* [OWNERS Upload Validator](#owners-upload-validator)
* [More Prolog Examples](#more-prolog-examples)

## Example from AOSP

The `find-owners` plugin is used in Android Open Source Project (AOSP).
Here is [one AOSP change](https://android-review.googlesource.com/c/platform/build/+/734949)
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`:
    ```bash
    [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.

1. Enable the upload validator in `project.config` of
   the `All-Projects` project, in the `refs/meta/config` branch:
    ```bash
    [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.

1. Optionally redefine **OWNERS** file name in `project.config` of
   some projects, in the `refs/meta/config` branch:
    ```bash
    [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.

1. Call the submit filters in `rules.pl` of `All-Projects`,
   in the `refs/meta/config` branch:
    ```prolog
    % 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](
      https://gerrit-review.googlesource.com/Documentation/prolog-change-facts.html),
      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](
https://gerrit-review.googlesource.com/Documentation/config-project-config.html#file-rules_pl)
in the `refs/meta/config` branch like this:

```prolog
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:

```prolog
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.

```bash
[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.

```prolog
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.

```prolog
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.

```prolog
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.

```prolog
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.

```prolog
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.