Add a documentation page for submit requirements Change-Id: I25cd93c1f0871db46198e4767c5df068a251ca3e
diff --git a/Documentation/config-submit-requirements.txt b/Documentation/config-submit-requirements.txt new file mode 100644 index 0000000..465cb53 --- /dev/null +++ b/Documentation/config-submit-requirements.txt
@@ -0,0 +1,240 @@ += 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_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. + +[[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 +---- + +GERRIT +------ +Part of link:index.html[Gerrit Code Review] + +SEARCHBOX +---------