Gerrit Code Review - Prolog Submit Rules Cookbook

Let’s start with a most trivial example where we would make every change submittable regardless of the votes it has:

In this case we make no use of facts about the change. We don’t need it as we are simply making every change submittable. Note that, in this case, the Gerrit UI will not show the UI for voting for the standard 'Code-Review' and 'Verified' categories as labels with these names are not part of the return result. The 'Any-Label-Name' could really be any string.

This is continuation of the previous example where, in addition, to making every change submittable we want to enable voting in the standard 'Code-Review' and 'Verified' categories.

Since for every change all label statuses are 'ok' every change will be submittable. Voting in the standard labels will be shown in the UI as the standard label names are included in the return result.

This example shows how to make all changes non-submittable regardless of the votes they have.

Since for any change we return only one label with status reject, no change will be submittable. The UI will, however, not indicate what is needed for a change to become submittable as we return no labels with status need.

In this example no change is submittable but here we show how to present Need <label> information to the user in the UI.

In the UI this will show:

From the example above we can see a few more things:

This example shows that, when there is a solution for submit_rule(X) where all labels have status ok then Gerrit will not show any labels with the need status from any of the previous submit_rule(X) solutions.

The Need Some-Condition will not be show in the UI because of the result of the second rule.

The same is valid if the two rules are swapped:

The result of the first rule will stop search for any further solutions.

This is the first example where we will use the Prolog facts about a change that are automatically exposed by Gerrit. Our goal is to make any change submittable when the commit author is named 'John Doe'. In the very first step let’s make sure Gerrit UI shows Need Author-is-John-Doe in the UI to clearly indicate to the user what is needed for a change to become submittable:

This will show:

in the UI but no change will be submittable yet. Let’s add another rule:

In the second rule we return ok status for the 'Author-is-John-Doe' label if there is a commit_author fact where the full name is 'John Doe'. If author of a change is 'John Doe' then the second rule will return a solution where all labels have ok status and the change will become submittable. If author of a change is not 'John Doe' then only the first rule will produce a solution. The UI will show Need Author-is-John-Doe but, as expected, the change will not be submittable.

Instead of checking by full name we could also check by the email address:

or by user id (assuming it is 1000000):

or by a combination of these 3 attributes:

Besides showing how to make use of the commit message text the purpose of this example is also to show how to match only a part of a string symbol. Similarly like commit author the commit message is provided as a string symbol which is an atom in Prolog terms. When working with an atom we could only match against the whole value. To match only part of a string symbol we have, at least, two options:

Let’s implement both options:

The starts_with predicate is self explaining.

Using the gerrit:commit_message_matches predicate is probably more efficient:

The previous example could also be written so that it first checks if the commit message starts with 'Fix '. If true then it sets OK for that category and stops further backtracking by using the cut ! operator: .rules.pl

The default submit rule with the two default categories, Code-Review and Verified, can be implemented as:

Once this implementation is understood it can be customized to implement project specific submit rules. Note, that this implementation hardcodes the two default categories. Introducing a new category in the database would require introducing the same category here or a submit_filter in a parent project would have to care about including the new category in the result of this submit_rule. On the other side, this example is easy to read and understand.

To get results of Gerrits default submit policy we use the gerrit:default_submit predicate. The gerrit:default_submit(X) includes all categories from the database. This means that if we write a submit rule like:

then this is equivalent to not using rules.pl at all. We just delegate to default logic. However, once we invoke the gerrit:default_submit(X) we can perform further actions on the return result X and apply our specific logic. The following pattern illustrates this technique:

In the following examples both styles will be shown.

In this example we introduce a new label Non-Author-Code-Review and make it satisfied if there is at least one Code-Review+2 from a non author. All other default policies like the Verified category and vetoing changes still apply.

A project has no build and test. It consists of only text files and needs only code review. We want to remove the Verified category from this project so that Code-Review+2 is the only criteria for a change to become submittable. We also want the UI to not show the Verified category in the table with votes and on the voting screen.

This is quite simple without reusing the 'gerrit:default_submit`:

Implementing the same rule by reusing gerrit:default_submit is a bit more complex:

In this example we want to both remove the verified and have the four eyes principle. This means we want a combination of examples 7 and 8.

The remove_verified_category and add_non_author_approval predicates are the same as defined in the previous two examples.

Without reusing the gerrit:default_submit the same example may be implemented as:

Example 9, implements submit_rule that removes the Verified category from one project. In this example we do the same but we want to remove the Verified category from all projects. This means we have to implement submit_filter and we have to do that in the rules.pl of the All-Projects project.

A new category DrNo is added to the database and is required for release branches. To mark a branch as a release branch we use drno('refs/heads/branch').

In this example we introduce accumulative voting to determine if a change is submittable or not. We modify the standard Code-Review to be accumulative, and make the change submittable if the total score is 2 or higher.

The code in this example is very similar to Example 8, with the addition of findall/3 and gerrit:remove_label. The findall/3 embedded predicate is used to form a list of all objects that satisfy a specified Goal. In this example it is used to get a list of all the Code-Review scores. gerrit:remove_label is a built-in helper that is implemented similarly to the remove_verified_category as seen in the previous example.

Implementing the same example without using gerrit:default_submit:

The master and apprentice example allow you to specify a user (the master) that must approve all changes done by another user (the apprentice).

The code first checks if the commit author is in the apprentice database. If the commit is done by an apprentice, it will check if there is a +2 review by the associated master.

This example adds a new needed category Patchset-Author for any user that is not the author of the patch. This effectively blocks all users except the author from submitting the change. This could result in an impossible situation if the author does not have permissions for submitting the change.

This example sets the Cherry Pick submit type for all changes. It overrides whatever is set as project default submit type.

rules.pl

For all refs/heads/stable.* branches we would like to enforce the Fast Forward Only submit type. A reason for this decision may be a need to never break the build in the stable branches. For all other branches, those not matching the refs/heads/stable.* pattern, we would like to use the project’s default submit type as defined on the project settings page.

The first submit_type predicate defines the Fast Forward Only submit type for refs/heads/stable.* branches. The second submit_type predicate returns the project’s default submit type.

Like in the previous example we want the Fast Forward Only submit type for the refs/heads/stable* branches. However, if only documentation was changed (only *.txt files), then we allow project’s default submit type for such changes.

The gerrit:commit_delta('(?<!\.txt)$') succeeds if the change contains a file whose name doesn’t end with .txt The rest of this rule is same like in the previous example.

If all file names in the change end with .txt, then the gerrit:commit_delta('(?<!\.txt)$') will fail as no file name will match this regular expression.