Reviewpad Semantics

A Reviewpad configuration file goes through a series of syntactic checks.

Syntactic checks

Unused rule

Each rule specified in the rules section must be used in a workflow. The following file is not valid since dummyRule is not used in any workflow.

api-version: reviewpad.com/v2.x

labels:
  fastTrack:
    description: fast track mode
    color: 76dbbe

rules:
  - name: changesOneFile
     kind: patch
     description: Patch has more one file
     spec: $fileCount == 1

  - name: dummyRule
     kind: patch
     description: Simple dummy rule
     spec: 1 == 1

workflows:
  - name: fastTrack
    description: Fast track of pull requests
    if:
      - rule: changesOneFile
    then:
      - $addLabel("fastTrack")

Reference to undefined rule

Each rule referenced in a workflow must be defined in the rules section. The following file is not valid as changesOneFile is not defined.

api-version: reviewpad.com/v2.x

labels:
  fastTrack:
    description: fast track mode
    color: 76dbbe

rules:

workflow:
  - name: fastTrack
    description: Fast track of pull requests
    if:
      - rule: changesOneFile
    then:
      - $addLabel("fastTrack")

Interpreter

If a Reviewpad configuration file is syntactically valid, then it will be passed to the interpreter.

This interpreter receives the file and an environment as input and if no error is found during the interpretation, it outputs an Aladino program to be executed.

Environment

The environment used by the interpreter is specified in the reviewpad/action:

  1. GitHub repository (e.g. google/guava);
  2. Pull request number (e.g. for https://github.com/google/guava/pull/5929 it would be 5929);
  3. Access token. By default, it uses automatic token authentication. For more information read https://docs.github.com/en/actions/security-guides/automatic-token-authentication.

Design decisions

The task of the interpreter is to traverse the workflow list to find which (if any) workflow is enabled in the environment.

The workflows that are enabled and subsequently which program will be executed respect the following rules:

  1. A workflow is enabled if and only if any of its rules evaluates to true.
  2. The order in which the workflows are specified determines the evaluation order.
  3. The final program is built by iterating over all workflows in the specified list.
  4. Only one workflow with always-run: false is enabled per execution.
  5. The evaluation of workflow is lazy, i.e. as soon as a workflow is activated, all the others are disregarded unless they have alwaysRun: true.

For example, consider the following pseudo Reviewpad file:

api-version: reviewpad.com/v2.x

rules:
 rule_1
 rule_2

workflows:
  - name: workflow_1
    description: Workflow 1
    if:
      - rule: rule_1
    then:
      - action_1

  - name: workflow_2
    description: Workflow 2
    if:
      - rule: rule_1
      - rule: rule_2
    then:
      - action_2

The interpreter starts by evaluating the rules of workflow_1 and only if all the rules are false it will go evaluate the rules of workflow_2. At the moment, there is no caching between rules.

If rule_1 is true, then workflow_1 would be active. As a consequence workflow_2 would never be evaluated and therefore rule_2.

The specification of the rules only contains read-only actions.

Program generation

As we mentioned, the interpreter will produce an Aladino program that will be executed.
This program is simply a sequence of actions.

We will use an example to illustrate how this program is generated. Assume that we have the following workflow:

  - name: workflow_X
    description: Active workflow
    if:
      - rule: rule_1
        extra-actions:
          - rule_1_action_1
          - rule_1_action_2
      - rule: rule_2
        extra-actions:
          - rule_2_action_1
      - rule: rule_3
      - rule: rule_4
        extra-actions:
          - rule_4_action_1
    then:
      - gen_action_1
      - gen_action_2

Assume that rule_1, rule_3 and rule_4 evaluate to true and rule_2 to false.

It follows that workflow_X is active. The final program is generated by concatenating the general actions of the workflow with the extra actions of each enabled rule.

In this case this would be:

gen_action_1
gen_action_2
rule_1_action_1
rule_1_action_2
rule_4_action_1

Note: The order in which both workflow and rules are specified matters. This is similar to any programming language where the order of statements matters.


Did this page help you?