1 of 48

Labels & Prolog-Less Submit Rules

Control when changes become submittable

(Edwin Kempin, Google)

2 of 48

Agenda

  • Overview - When is a change submittable?
  • Labels
  • Prolog-less Submit Rules
  • Why not Prolog?
  • Future Work

3 of 48

When is a change submittable?

?

4 of 48

When is a change submittable?

  • Submit Permission���

5 of 48

When is a change submittable?

  • Submit Permission���
  • Not

6 of 48

When is a change submittable?

  • Submit Permission���
  • Not
  • No

7 of 48

When is a change submittable?

  • Submit Permission���
  • Not
  • No
  • Parent changes are submittable*�
  • All changes in topic are submittable**

* if submit type != CHERRY_PICK�** if change.submitWholeTopic = true

8 of 48

When is a change submittable?

  • Approvals��
  • No veto votes�
  • Submit Permission���
  • Not
  • No
  • Parent changes are submittable*�
  • All changes in topic are submittable**

* if submit type != CHERRY_PICK�** if change.submitWholeTopic = true

9 of 48

  • Submit Permission���
  • Not
  • No
  • Parent changes are submittable*�
  • All changes in topic are submittable**

When is a change submittable?

  • Approvals��
  • No veto votes��
  • Results of custom submit rules

* if submit type != CHERRY_PICK�** if change.submitWholeTopic = true

10 of 48

When is a change submittable?

  • Approvals��
  • No veto votes��
  • Results of custom submit rules

Hard-coded in Gerrit

Label Configuration (DefaultSubmitRule)

SubmitRules

* if submit type != CHERRY_PICK�** if change.submitWholeTopic = true

  • Submit Permission���
  • Not
  • No
  • Parent changes are submittable*�
  • All changes in topic are submittable**

11 of 48

Where are Prolog submit rules?

* if submit type != CHERRY_PICK�** if change.submitWholeTopic = true

12 of 48

Where are Prolog submit rules?

  • Approvals��
  • No veto votes�

Prolog Submit Rules (PrologRule)

* if submit type != CHERRY_PICK�** if change.submitWholeTopic = true

13 of 48

Label Configuration

(details in Gerrit docs)

14 of 48

Label Configuration

  • Approvals��
  • No veto votes��

Label Configuration (DefaultSubmitRule)

* if submit type != CHERRY_PICK�** if change.submitWholeTopic = true

15 of 48

File project.config in refs/meta/config:

Label Configuration - Example�

[label "MyLabel"]� function = MaxWithBlock� value = -1 Veto� value = 0 No score� value = +1 Approval

16 of 48

File project.config in refs/meta/config:

Label Configuration - Example�

[label "MyLabel"]� function = MaxWithBlock� value = -1 Veto� value = 0 No score� value = +1 Approval

17 of 48

Label Functions�

  • Whether approval* is required for submit
  • Whether veto** blocks submit

* Approval = highest possible vote�** Veto = lowest possible vote

Function

Approval required

Veto possible

MaxWithBlock (default)

​

​

AnyWithBlock

​

​

MaxNoBlock

​

​

NoBlock

​

​

18 of 48

  • branch can be set to an exact ref, a ref pattern or a regular expression

Restrict Label to Branch�

[label "MyLabel"]� function = MaxWithBlock� value = -1 Veto� value = 0 No score� value = +1 Approval� branch = refs/heads/stable/*

19 of 48

  • Whether existing votes should be preserved when a new patch set is uploaded.
  • Copy rules can be configured per label:

Sticky Labels

[label "MyLabel"]� function = MaxWithBlock� value = -1 Veto� value = 0 No score� value = +1 Approval� copyMinScore = true

20 of 48

Copy Rules�

* Veto = lowest possible vote

** Approval = highest possible vote

*** Trivial Rebase = same commit message and same code diff

Copy Rule

Behavior

copyMinScore

Makes vetos* sticky.

copyMaxScore

Makes approvals** sticky.

copyAllScoresIfNoCodeChange

Makes votes sticky if only the commit message was changed.

copyAllScoresOnTrivialRebase

Makes votes sticky if the new patch set was a trivial rebase*** of the old patch set.

21 of 48

Label Inheritance

  • Labels defined on a parent project apply to all child projects.

[label "MyLabel"]� function = MaxWithBlock� value = -1 Veto� value = 0 No score� value = +1 Approval

Parent

Child

22 of 48

Label Inheritance

  • Child projects need a complete label definition to override an inherited label.

[label "MyLabel"]� function = MaxWithBlock� value = -1 Veto� value = 0 No score� value = +1 Approval

Parent

Child

[label "MyLabel"]� function = MaxWithBlock� value = -2 Veto� value = -1 Please fix� value = 0 No score� value = +1 LGTM� value = +2 Approval

23 of 48

Label Inheritance

  • An empty label definition removes an inherited label.

[label "MyLabel"]� function = MaxWithBlock� value = -1 Veto� value = 0 No score� value = +1 Approval

Parent

Child

[label "MyLabel"]

24 of 48

Label Inheritance

  • Parent projects can enforce labels for child projects.

[label "MyLabel"]� function = MaxWithBlock� value = -1 Veto� value = 0 No score� value = +1 Approval� canOverride = false

Parent

Child

[label "MyLabel"]

Ignored

25 of 48

  • Not everything can be expressed with labels, e.g.:
    • Require non-author code review.
    • Require no unresolved comments.
    • Require bug footer in commit message.

�

  • Large number of labels doesn’t scale well�

Limitations of Labels

26 of 48

Limitations of Labels

  • Not everything can be expressed with labels, e.g.:
    • Require non-author code review.
    • Require no unresolved comments.
    • Require bug footer in commit message.

⇒ Submit Rules�

  • Large number of labels doesn’t scale well�⇒ Checks (see talk from Alice earlier today)�

27 of 48

Submit Rules vs. Checks

Submit Rules

Checks

Supported by Gerrit core.

Need checks plugin.

Run inside Gerrit process.

Run outside of Gerrit process (on CI server).

Executed when submittability of a change is checked.

Executed (at most) once per patch set.

Synchronous.

Asynchronous.

One submit requirement per submit rule.

One aggregated result per change.

28 of 48

Submit Rules for Checks

SubmitRules

ChecksSubmitRule

* if submit type != CHERRY_PICK�** if change.submitWholeTopic = true

29 of 48

Prolog-less Submit Rule

(details in Gerrit docs)

30 of 48

Prolog-less Submit Rules

  • Results of custom submit rules

SubmitRules

* if submit type != CHERRY_PICK�** if change.submitWholeTopic = true

31 of 48

SubmitRule Extension Point

Shown interface is from master (aka Gerrit 3.1).�Exists since 2.16, but looks slightly different there.

  • Allows plugins to write submit rules.
  • Are written in Java or any other language

32 of 48

Example: No Unresolved Comments

Full code can be found in the simple-submit-rule plugin.

33 of 48

Example: No Unresolved Comments

Full code can be found in the simple-submit-rule plugin.

  1. Read plugin config and check if the rule is enabled

34 of 48

Example: No Unresolved Comments

Full code can be found in the simple-submit-rule plugin.

  • Read plugin config and check if the rule is enabled
  • Get number of unresolved comments

35 of 48

Example: No Unresolved Comments

Full code can be found in the simple-submit-rule plugin.

  • Read plugin config and check if the rule is enabled
  • Get number of unresolved comments
  • Create SubmitRecord and set status depending on number of unresolved comments.

36 of 48

Example: No Unresolved Comments

Full code can be found in the simple-submit-rule plugin.

  • Read plugin config and check if the rule is enabled
  • Get number of unresolved comments
  • Create SubmitRecord and set status depending on number of unresolved comments.
  • Error handling

37 of 48

Example: No Unresolved Comments

The result of the SubmitRule is shown here

38 of 48

simple-submit-rules Plugin

  • Provides SubmitRule for unresolved comments.

​

​

​

  • Provides UI for configuring labels:

39 of 48

simple-submit-rules Plugin

  • Bucket to try out new submit rules
  • Possibly include successful rules into Gerrit core�⇒ The submit rule to ignore self approval was already � moved into core (contained since 2.16).������
  • Example plugin for submit rules�⇒ e.g. shows how to configure submit rules from UI

[label "MyLabel"]� function = MaxWithBlock� value = -1 Veto� value = 0 No score� value = +1 Approval� ignoreSelfApproval = true

40 of 48

  • Change is not submittable if any submit rules returns a non-fulfilled requirement

Results from multiple Submit Rules

41 of 48

  • If wanted, inheritance can be handled within the plugin

SubmitRule: Handling of Inheritance

Also look at the project configuration of parent projects

42 of 48

  • Not flexible, need to write a plugin.�⇒ rules cannot be added/modified adhoc
  • Not guaranteed to be hermetic.�⇒ Responsibility of SubmitRule author.

Limitations of Submit Rules

43 of 48

Why not Prolog?

44 of 48

Why not Prolog?

  • Approvals��
  • No veto votes�

Prolog Submit Rules (PrologRule)

* if submit type != CHERRY_PICK�** if change.submitWholeTopic = true

45 of 48

  • Nobody knows/likes Prolog�⇒ project owners cut & paste from cookbook�⇒ leads to increased support load for Gerrit admins
  • Any requirement appears as label�⇒ misuse of labels�⇒ doesn’t scale well
  • Error-Prone�⇒ Errors may stay unnoticed (e.g. everything is submittable)
  • Not easily testable�⇒ never saw an integration test for a Prolog rule
  • Some properties of label definition are ignored�⇒ e.g. branch property

Why not Prolog?

46 of 48

Future Work

47 of 48

  • Move submit rule for unresolved comments into core?
  • Move UI to edit labels into core?
  • Implement more submit rules in simple-submit-rules plugin
  • Move Prolog support into a plugin�⇒ PrologRule already implements SubmitRule
  • Experiment with scripting engines�⇒ see scripting-rules plugin (Lua, JS)

Possible Future Work*

*Wishlist, currently nobody is actively working on these points..

48 of 48

Questions?