| = 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. |
| |
| 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_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 |
| --------- |