| = 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 | |
| ---- | |
| Branch configuration supports regular expressions as well, e.g. to exempt 'refs/heads/release/*' pattern, | |
| when migrating from the label Submit-Rule: | |
| ---- | |
| [label "Verified"] | |
| branch = refs/heads/release/* | |
| ---- | |
| The following SR can be configured: | |
| ---- | |
| [submit-requirement "Verified"] | |
| submittableIf = label:Verified=MAX AND -label:Verified=MIN | |
| applicableIf = branch:^refs/heads/release/.* | |
| ---- | |
| [[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 | |
| --------- |