Documentation/config-submit-requirements.txt

= Gerrit Code Review - Submit Requirements

As part of the code review process, project owners need to configure rules that
govern when changes become submittable. For example, an admin might want to
prevent changes from being submittable until at least a “+2” vote on the
“Code-Review” label is granted on a change. Admins can define submit
requirements to enforce submittability rules for changes.

[[configuring_submit_requirements]]
== Configuring Submit Requirements

Site administrators and project owners can define submit requirements in the
link:config-project-config.html[project config]. A submit requirement has the
following fields:


[[submit_requirement_name]]
=== submit-requirement.Name

A name that uniquely identifies the submit requirement. Submit requirements
can be overridden in child projects if they are defined with the same name in
the child project. See the link:#inheritance[inheritance] section for more
details.

[[submit_requirement_description]]
=== submit-requirement.Name.description

A detailed description of what the submit requirement is supposed to do. This
field is optional. The description is visible to the users in the change page
upon hovering on the submit requirement to help them understand what the
requirement is about and how it can be fulfilled.

[[submit_requirement_applicable_if]]
=== submit-requirement.Name.applicableIf

A link:#query_expression_syntax[query expression] that determines if the submit
requirement is applicable for a change. For example, administrators can exclude
submit requirements for certain branch patterns. See the
link:#exempt-branch-example[exempt branch] example.

Often submit requirements should only apply to branches that contain source
code. In this case this parameter can be used to exclude the
link:config-project-config.html#refs-meta-config[refs/meta/config] branch from
a submit requirement:

----
  applicableIf = -branch:refs/meta/config
----

This field is optional, and if not specified, the submit requirement is
considered applicable for all changes in the project.

[[submit_requirement_submittable_if]]
=== submit-requirement.Name.submittableIf

A link:#query_expression_syntax[query expression] that determines when the
change becomes submittable. This field is mandatory.


[[submit_requirement_override_if]]
=== submit-requirement.Name.overrideIf

A link:#query_expression_syntax[query expression] that controls when the
submit requirement is overridden. When this expression is evaluated to true,
the submit requirement state becomes `OVERRIDDEN` and the submit requirement
is no longer blocking the change submission.
This expression can be used to enable bypassing the requirement in some
circumstances, for example if the change owner is a power user or to allow
change submission in case of emergencies. +

This field is optional.

[[submit_requirement_can_override_in_child_projects]]
=== submit-requirement.Name.canOverrideInChildProjects

A boolean (true, false) that determines if child projects can override the
submit requirement. +

The default value is `false`.

[[evaluation_results]]
== Evaluation Results

When submit requirements are configured, their results are returned for all
changes requested by the REST API with the
link:rest-api-changes.html#submit-requirement-result-info[SubmitRequirementResultInfo]
entity. +

Submit requirement results are produced from the evaluation of the submit
requirements in the project config (
See link:#configuring_submit_requirements[Configuring Submit Requirements])
as well as the conversion of the results of the legacy submit rules to submit
requirement results. Legacy submit rules are label functions
(see link:config-labels.html[config labels]), custom and
link:prolog-cookbook.html[prolog] submit rules.

The `status` field can be one of:

* `NOT_APPLICABLE`
+
The link:#submit_requirement_applicable_if[applicableIf] expression evaluates
to false for the change.

* `UNSATISFIED`
+
The submit requirement is applicable
(link:#submit_requirement_applicable_if[applicableIf] evaluates to true), but
the evaluation of the link:#submit_requirement_submittable_if[submittableIf] and
link:#submit_requirement_override_if[overrideIf] expressions return false for
the change.

* `SATISFIED`
+
The submit requirement is applicable
(link:#submit_requirement_applicable_if[applicableIf] evaluates to true), the
link:#submit_requirement_submittable_if[submittableIf] expression evaluates to
true, and the link:#submit_requirement_override_if[overrideIf] evaluates to
false for the change.

* `OVERRIDDEN`
+
The submit requirement is applicable
(link:#submit_requirement_applicable_if[applicableIf] evaluates to true) and the
link:#submit_requirement_override_if[overrideIf] expression evaluates to true.
+
Note that in this case, the change is overridden whether the
link:#submit_requirement_submittable_if[submittableIf] expression evaluates to
true or not.

* `BYPASSED`
+
The change was merged directly bypassing code review by supplying the
link:user-upload.html#auto_merge[submit] push option while doing a git push.

* `ERROR`
+
The evaluation of any of the
link:#submit_requirement_applicable_if[applicableIf],
link:#submit_requirement_submittable_if[submittableIf] or
link:#submit_requirement_override_if[overrideIf] expressions resulted in an
error.


[[query_expression_syntax]]
== Query Expression Syntax

All applicableIf, submittableIf and overrideIf expressions use the same syntax
and operators available for link:user-search.html[searching changes]. In
addition to that, submit requirements support extra operators.


[[submit_requirements_operators]]
=== Submit Requirements Operators

[[operator_authoremail]]
authoremail:'EMAIL_PATTERN'::
+
An operator that returns true if the change author's email address matches a
specific regular expression pattern. The
link:http://www.brics.dk/automaton/[dk.brics.automaton library,role=external,window=_blank]
is used for the evaluation of such patterns.

[[operator_distinctvoters]]
distinctvoters:'[Label1,Label2,...,LabelN],value=MAX,count>1'::
+
An operator that allows checking for distinct voters across more than one label.
+
2..N labels are supported, filtering by a value (MIN,MAX,integer) is optional.
Count is mandatory.
+
Examples:
`distinctvoters:[Code-Review,Trust],value=MAX,count>1`
+
`distinctvoters:[Code-Review,Trust,API-Review],count>2`

[[operator_is_true]]
is:true::
+
An operator that always returns true for all changes. An example usage is to
redefine a submit requirement in a child project and make the submit requirement
always applicable.

[[operator_is_false]]
is:false::
+
An operator that always returns false for all changes. An example usage is to
redefine a submit requirement in a child project and make the submit requirement
always non-applicable.

[[operator_has_submodule_update]]
has:submodule-update::
+
An operator that returns true if the diff of the latest patchset against the
default parent has a submodule modified file, that is, a ".gitmodules" or a
git link file.
+
The optional `base` parameter can also be supplied for merge commits like
`has:submodule-update,base=1`, or `has:submodule-update,base=2`. In these cases,
the operator returns true if the diff of the latest patchset against parent
number identified by `base` has a submodule modified file. Note that the
operator will return false if the base parameter is greater than the number of
parents for the latest patchset for the change.

[[operator_file]]
file:"'<filePattern>',withDiffContaining='<contentPattern>'"::
+
An operator that returns true if the latest patchset contained a modified file
matching `<filePattern>` with a modified region matching `<contentPattern>`.

[[unsupported_operators]]
=== Unsupported Operators

Some operators are not supported with submit requirement expressions.

[[operator_is_submittable]]
is:submittable::
+
Cannot be used since it will result in recursive evaluation of expressions.

[[inheritance]]
== Inheritance

Child projects can override a submit requirement defined in any of their parent
projects. Overriding a submit requirement overrides all of its properties and
values. The overriding project needs to define all mandatory fields.

Submit requirements are looked up from the current project up the inheritance
hierarchy to “All-Projects”. The first project in the hierarchy chain that sets
link:#submit_requirement_can_override_in_child_projects[canOverrideInChildProjects]
to false prevents all descendant projects from overriding it.

If a project disallows a submit requirement from being overridden in child
projects, all definitions of this submit requirement in descendant projects are
ignored.

To remove a submit requirement in a child project, administrators can redefine
the requirement with the same name in the child project and set the
link:#submit_requirement_applicable_if[applicableIf] expression to `is:false`.
Since the link:#submit_requirement_submittable_if[submittableIf] field is
mandatory, administrators need to provide it in the child project but can set it
to anything, for example `is:false` but it will have no effect anyway.


[[trigger-votes]]
== Trigger Votes

Trigger votes are label votes that are not associated with any submit
requirement expressions. Trigger votes are displayed in a separate section in
the change page. For more about configuring labels, see the
link:config-labels.html[config labels] documentation.


[[examples]]
== Examples

[[code-review-example]]
=== Code-Review Example

To define a submit requirement for code-review that requires a maximum vote for
the “Code-Review” label from a non-uploader without a maximum negative vote:

----
[submit-requirement "Code-Review"]
	description = A maximum vote from a non-uploader is required for the \
	              'Code-Review' label. A minimum vote is blocking.
	submittableIf = label:Code-Review=MAX,user=non_uploader AND -label:Code-Review=MIN
	canOverrideInChildProjects = true
----

[[exempt-branch-example]]
=== Exempt a branch Example

We could exempt a submit requirement from certain branches. For example,
project owners might want to skip the 'Code-Style' requirement from the
refs/meta/config branch.

----
[submit-requirement "Code-Style"]
  description = Code is properly styled and formatted
  applicableIf = -branch:refs/meta/config
  submittableIf = label:Code-Style=+1 AND -label:Code-Style=-1
  canOverrideInChildProjects = true
----


[[test-submit-requirements]]
== Testing Submit Requirements

The link:rest-api-changes.html#check-submit-requirement[Check Submit Requirement]
change endpoint can be used to test submit requirements on any change. Users
are encouraged to test submit requirements before adding them to the project
to ensure they work as intended.

.Request
----
  POST /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/check.submit_requirement HTTP/1.0
  Content-Type: application/json; charset=UTF-8

    {
      "name": "Code-Review",
      "submittability_expression": "label:Code-Review=+2"
    }
----

.Response
----
  HTTP/1.1 200 OK
  Content-Disposition: attachment
  Content-Type: application/json; charset=UTF-8

  )]}'
  {
    "name": "Code-Review",
    "status": "SATISFIED",
    "submittability_expression_result": {
      "expression": "label:Code-Review=+2",
      "fulfilled": true,
      "passingAtoms": [
        "label:Code-Review=+2"
      ]
    },
    "is_legacy": false
  }
----

GERRIT
------
Part of link:index.html[Gerrit Code Review]

SEARCHBOX
---------