| = Gerrit Code Review - Review Labels | |
| As part of the code review process, reviewers score each change with | |
| values for each label configured for the project. The label values that | |
| a given user is allowed to set are defined according to the | |
| link:access-control.html#category_review_labels[access controls]. Gerrit | |
| comes pre-configured with the Code-Review label that can be granted to | |
| groups within projects, enabling functionality for that group's members. | |
| Project owners and admins might also need to configure rules which require | |
| labels to be voted before a change can be submittable. See the | |
| link:config-submit-requirements.html[submit requirements] documentation to | |
| configure such rules. | |
| [[sticky_votes]] | |
| == Sticky Votes | |
| Whether votes are sticky when a new patch set is created depends on the | |
| link:#label_copyCondition[copyCondition] of the label. If an approval | |
| matches the configured condition it is copied from the old current | |
| patch set to the new current patch set. Votes that are not copied to | |
| the new patch set, are called `outdated`. | |
| If votes get outdated due to pushing a new patch set the uploader is | |
| informed about this by a message in the git output. In addition, | |
| outdated votes are also listed in the email notification that is sent | |
| for the new patch set (unless this is disabled by a custom email | |
| template). Note, that the uploader only get this email notification if | |
| they have configured `Every Comment` for `Email notifications` in their | |
| user preferences. With any other email preference the email sender, the | |
| uploader in this case, is not included in the email recipients. | |
| If votes get outdated due to creating a new patch set the user of the | |
| removed vote is added to the attention set of the change, as they need | |
| to re-review the change and renew their vote. | |
| If a vote is applied on an outdated patch set (i.e. a patch set that is | |
| not the current patch set) the vote is copied forward to follow-up | |
| patch sets if possible. A newly added or updated vote on an outdated | |
| patch set is copied to follow-up patch sets if: | |
| * the vote is copyable (i.e. it matches the | |
| link:#label_copyCondition[copyCondition] of the label) | |
| * neither the follow-up patch set nor an intermediate patch set has a | |
| non-copied vote or a deletion vote (vote with value `0`) that | |
| overrides the copy vote | |
| If an approval on an outdated patch set is removed or updated to a | |
| value that is not copyable, existing copies of that approval on | |
| follow-up patch sets are removed. | |
| [[label_Code-Review]] | |
| == Label: Code-Review | |
| The Code-Review label is configured upon the creation of a Gerrit | |
| instance. It may have any meaning the project desires. It was | |
| originally invented by the Android Open Source Project to mean | |
| 'I read the code and it seems reasonably correct'. | |
| The range of values is: | |
| * -2 This shall not be submitted | |
| + | |
| The code is so horribly incorrect/buggy/broken that it must not be | |
| submitted to this project, or to this branch. This value is valid | |
| across all patch sets in the same change, i.e. the reviewer must | |
| actively change his/her review to something else before the change | |
| is submittable. | |
| + | |
| *Any -2 blocks submit.* | |
| * -1 I would prefer this is not submitted as is | |
| + | |
| The code doesn't look right, or could be done differently, but | |
| the reviewer is willing to live with it as-is if another reviewer | |
| accepts it, perhaps because it is better than what is currently in | |
| the project. Often this is also used by contributors who don't like | |
| the change, but also aren't responsible for the project long-term | |
| and thus don't have final say on change submission. | |
| + | |
| Does not block submit. | |
| * 0 No score | |
| + | |
| Didn't try to perform the code review task, or glanced over it but | |
| don't have an informed opinion yet. | |
| * +1 Looks good to me, but someone else must approve | |
| + | |
| The code looks right to this reviewer, but the reviewer doesn't | |
| have access to the `+2` value for this category. Often this is | |
| used by contributors to a project who were able to review the change | |
| and like what it is doing, but don't have final approval over what | |
| gets submitted. | |
| * +2 Looks good to me, approved | |
| + | |
| Basically the same as `+1`, but for those who have final say over | |
| how the project will develop. | |
| + | |
| *Any +2 enables submit.* | |
| For a change to be submittable, the latest patch set must have a | |
| `+2 Looks good to me, approved` in this category, and no | |
| `-2 This shall not be submitted`. Thus `-2` on any patch set can | |
| block a submit, while `+2` on the latest patch set can enable it. | |
| If a Gerrit installation does not wish to use this label in any project, | |
| the `[label "Code-Review"]` section can be deleted from `project.config` | |
| in `All-Projects`. | |
| If a Gerrit installation or project wants to modify the description text | |
| associated with these label values, the text can be updated in the | |
| `label.Code-Review.value` fields in `project.config`. | |
| Additional entries could be added to `label.Code-Review.value` to | |
| further extend the negative and positive range, but there is likely | |
| little value in doing so as this only expands the middle region. This | |
| label is a `MaxWithBlock` type, which means that the lowest negative | |
| value if present blocks a submit, while the highest positive value is | |
| required to enable submit. | |
| [[label_Verified]] | |
| == Label: Verified | |
| The Verified label was originally invented by the Android Open Source | |
| Project to mean 'compiles, passes basic unit tests'. Some CI tools | |
| expect to use the Verified label to vote on a change after running. | |
| During site initialization the administrator may have chosen to | |
| configure the default Verified label for all projects. In case it is | |
| desired to configure it at a later time, administrators can do this by | |
| adding the following to `project.config` in `All-Projects`: | |
| ---- | |
| [label "Verified"] | |
| function = MaxWithBlock | |
| value = -1 Fails | |
| value = 0 No score | |
| value = +1 Verified | |
| copyCondition = changekind:NO_CODE_CHANGE | |
| ---- | |
| The range of values is: | |
| * -1 Fails | |
| + | |
| Tried to compile, but got a compile error, or tried to run tests, | |
| but one or more tests did not pass. | |
| + | |
| *Any -1 blocks submit.* | |
| * 0 No score | |
| + | |
| Didn't try to perform the verification tasks. | |
| * +1 Verified | |
| + | |
| Compiled (and ran tests) successfully. | |
| + | |
| *Any +1 enables submit.* | |
| For a change to be submittable, the change must have a `+1 Verified` | |
| in this label, and no `-1 Fails`. Thus, `-1 Fails` can block a submit, | |
| while `+1 Verified` enables a submit. | |
| Additional values could also be added to this label, to allow it to | |
| behave more like `Code-Review` (below). Add -2 and +2 entries to the | |
| `label.Verified.value` fields in `project.config` to get the same | |
| behavior. | |
| [[label_custom]] | |
| == Customized Labels | |
| Site administrators and project owners can define their own labels, | |
| or customize labels inherited from parent projects. | |
| See above for descriptions of how <<label_Verified,`Verified`>> | |
| and <<label_Code-Review,`Code-Review`>> work, and add your own | |
| label to `project.config` to get the same behavior over your own range | |
| of values, for any label you desire. | |
| Just like the built-in labels, users need to be given permissions to | |
| vote on custom labels. Permissions can either be added by manually | |
| editing project.config when adding the labels, or, once the labels are | |
| added, permission categories for those labels will show up in the | |
| permission editor web UI. | |
| Labels may be added to any project's `project.config`; the default | |
| labels are defined in `All-Projects`. | |
| [[label_inheritance]] | |
| === Inheritance | |
| Labels are inherited from parent projects. A child project may add, | |
| override, or remove labels defined in its parents. | |
| Overriding a label in a child project overrides all its properties and | |
| values. It is not possible to modify an inherited label by adding | |
| properties in the child project's configuration; all properties from | |
| the parent definition must be redefined in the child. | |
| To remove a label in a child project, add an empty label with a single "0" | |
| value, with the same name as in the parent. This will override the parent label | |
| with a label containing the defaults (`function = NoBlock`, | |
| `defaultValue = 0` and no further allowed values) | |
| [[label_layout]] | |
| === Layout | |
| Labels are laid out in alphabetical order. | |
| [[label_name]] | |
| === `label.Label-Name` | |
| The name for a label, consisting only of alphanumeric characters and | |
| `-`. | |
| [[label_description]] | |
| === `label.Label-Name.description` | |
| The label description. This field can provide extra information of what the | |
| label is supposed to do. | |
| [[label_value]] | |
| === `label.Label-Name.value` | |
| A multi-valued key whose values are of the form `"<#> Value description | |
| text"`. The `<#>` may be any positive or negative number with an | |
| optional leading `+`. | |
| [[label_defaultValue]] | |
| === `label.Label-Name.defaultValue` | |
| The default value (or score) for the label. The defaultValue must be | |
| within the range of valid label values. It is an optional label setting, | |
| if not defined the defaultValue for the label will be 0. When a | |
| defaultValue is defined, that value will get set in the Reply dialog | |
| by default. | |
| A defaultValue can be set to a score that is outside of the permissible | |
| range for a user. In that case the score that will get set in the Reply | |
| box will be either the lowest or highest score in the permissible range. | |
| [[label_function]] | |
| === `label.Label-Name.function (deprecated)` | |
| Label functions dictate the rules for requiring certain label votes before a | |
| change is allowed for submission. Label functions are **deprecated** and updates | |
| that set `function` to a blocking value {`MaxWithBlock`, `MaxNoBlock`, | |
| `AnyWithBlock`} will be rejected. Existing label function definitions can only | |
| be updated to {`NoBlock`, `NoOp`, `PatchSetLock`}. New label defintions should | |
| also explicitly set the `function` attribute to a non-blocking value since the | |
| default is `MaxWithBlock`. | |
| If your project has a | |
| blocking label function, we highly encourage you to change it to `NoBlock` and | |
| add a submit-requirement for the same label. See the | |
| link:config-submit-requirements.html#code-review-example[submit-requirements | |
| documentation] for more details. | |
| The name of a function for evaluating multiple votes for a label. This | |
| function is only applied if the default submit rule is used for a label. | |
| If you write a link:prolog-cookbook.html#HowToWriteSubmitRules[custom | |
| submit rule] (and do not call the default rule), the function name is | |
| ignored and may be treated as optional. | |
| Valid values are: | |
| * `MaxWithBlock` (default) | |
| + | |
| The lowest possible negative value, if present, blocks a submit, while | |
| the highest possible positive value is required to enable submit. There | |
| must be at least one positive value, or else submit will never be | |
| enabled. To permit blocking submits, ensure a negative value is defined. | |
| * `AnyWithBlock` | |
| + | |
| The label is not mandatory but the lowest possible negative value, | |
| if present, blocks a submit. To permit blocking submits, ensure that a | |
| negative value is defined. | |
| * `MaxNoBlock` | |
| + | |
| The highest possible positive value is required to enable submit, but | |
| the lowest possible negative value will not block the change. | |
| * `NoBlock`/`NoOp` | |
| + | |
| The label is purely informational and values are not considered when | |
| determining whether a change is submittable. | |
| * `PatchSetLock` | |
| + | |
| The `PatchSetLock` function provides a locking mechanism for patch | |
| sets. This function's values are not considered when determining | |
| whether a change is submittable. When set, no new patchsets can be | |
| created and rebase and abandon are blocked. This is useful to prevent | |
| updates to a change while (potentially expensive) CI | |
| validation is running. | |
| + | |
| This function is designed to allow overlapping locks, so several lock | |
| accounts could lock the same change. | |
| + | |
| Allowed range of values are 0 (Patch Set Unlocked) to 1 (Patch Set | |
| Locked). | |
| [[label_allowPostSubmit]] | |
| === `label.Label-Name.allowPostSubmit` | |
| If true, the label may be voted on for changes that have already been | |
| submitted. If false, the label will not appear in the UI and will not | |
| be accepted when reviewing a closed change. | |
| In either case, voting on a label after submission is only permitted if | |
| the new vote is at least as high as the old vote by that user. This | |
| avoids creating the false impression that a post-submit vote can change | |
| the past and affect submission somehow. | |
| Defaults to true. | |
| [[label_copyCondition]] | |
| === `label.Label-Name.copyCondition` | |
| If set, Gerrit matches patch set approvals against the provided query | |
| string. If the query matches, the approval is copied from one patch set | |
| to the next. The query language is the same as for | |
| link:user-search.html[other queries]. | |
| This logic is triggered whenever a new patch set is uploaded. | |
| Gerrit currently supports the following predicates: | |
| [[changekind]] | |
| ==== changekind:{NO_CHANGE,NO_CODE_CHANGE,MERGE_FIRST_PARENT_UPDATE,REWORK,TRIVIAL_REBASE} | |
| Matches if the diff between two patch sets was of a certain change kind: | |
| * [[no_change]]`NO_CHANGE`: | |
| + | |
| Matches when a new patch set is uploaded that has the same parent tree, | |
| code delta, and commit message as the previous patch set. This means | |
| that only the patch set SHA-1 is different. This can be used to enable | |
| sticky approvals, reducing turn-around for this special case. | |
| + | |
| It is recommended to leave this enabled for both, the Code-Review and | |
| the Verified labels. | |
| + | |
| `NO_CHANGE` is more trivial than a trivial rebase, no code change and | |
| a first parent update, hence this change kind is also matched by | |
| `changekind:TRIVIAL_REBASE`, `changekind:NO_CODE_CHANGE` and if it's | |
| a merge commit by `changekind:MERGE_FIRST_PARENT_UPDATE`. | |
| * [[no_code_change]]`NO_CODE_CHANGE`: | |
| + | |
| Matches when a new patch set is uploaded that has the same parent tree | |
| as the previous patch set and the same code diff (including context | |
| lines) as the previous patch set. This means only the commit message | |
| may be different; the change hasn't even been rebased. Also matches if | |
| the commit message is not different, which means this includes matching | |
| patch sets that have `NO_CHANGE` as the change kind. | |
| + | |
| This predicate can be used to enable sticky approvals on labels that | |
| only depend on the code, reducing turn-around if only the commit | |
| message is changed prior to submitting a change. | |
| + | |
| For the Verified label that is optionally installed by the | |
| link:pgm-init.html[init] site program this predicate is used by | |
| default. | |
| * [[merge_first_parent_update]]`MERGE_FIRST_PARENT_UPDATE`: | |
| + | |
| Matches when a new patch set is uploaded that is a new merge commit | |
| which only differs from the merge commit in the previous patch set in | |
| its first parent, or has identical parents (aka the change kind of the | |
| merge commit is `NO_CHANGE`). | |
| + | |
| The first parent of the merge commit is part of the change's target | |
| branch, whereas the other parent(s) refer to the feature branch(es) to | |
| be merged. | |
| + | |
| Matching this change kind is useful if you don't want to trigger CI or | |
| human verification again if your target branch moved on but the feature | |
| branch(es) being merged into the target branch did not change. | |
| + | |
| This predicate does not match if the patch set is not a merge commit. | |
| * [[trivial_rebase]]`TRIVIAL_REBASE`: | |
| + | |
| Matches when a new patch set is uploaded that is a trivial rebase. A | |
| new patch set is considered to be trivial rebase if the commit message | |
| is the same as in the previous patch set and if it has the same diff | |
| (including context lines) as the previous patch set. This is the case | |
| if the change was rebased onto a different parent and that rebase did | |
| not require git to perform any conflict resolution, or if the parent | |
| did not change at all (aka the change kind of the commit is | |
| `NO_CHANGE`). | |
| + | |
| This predicate can be used to enable sticky approvals, reducing | |
| turn-around for trivial rebases prior to submitting a change. | |
| + | |
| For the pre-installed Code-Review label this predicate is used by | |
| default. | |
| * [[rework]]`REWORK`: | |
| + | |
| Matches all kind of change kinds because any other change kind | |
| is just a more trivial version of a rework. This means setting | |
| `changekind:REWORK` is equivalent to setting `is:ANY`. | |
| [[is_magic]] | |
| ==== is:{MIN,MAX,ANY} | |
| Matches approvals that have a minimal, maximal or any score: | |
| * [[is_min]]`MIN`: | |
| + | |
| Matches approvals that have a minimal score, i.e. the lowest possible | |
| (negative) value for this label. | |
| * [[is_max]]`MAX`: | |
| + | |
| Matches approvals that a maximal score, i.e. the highest possible | |
| (positive) value for this label. | |
| * [[is_any]]`ANY`: | |
| + | |
| Matches any approval when a new patch set is uploaded. | |
| [[is_value]] | |
| ==== is:'VALUE' | |
| Matches approvals that have a voting value that is equal to 'VALUE'. | |
| Negative values need to be quoted, e.g.: is:"-1" | |
| [[approverin]] | |
| ==== approverin:link:#group-id[\{group-id\}] | |
| Matches votes granted by a user who is a member of | |
| link:#group-id[\{group-id\}]. | |
| [[uploaderin]] | |
| ==== uploaderin:link:#group-id[\{group-id\}] | |
| Matches all votes if the new patch set was uploaded by a member of | |
| link:#group-id[\{group-id\}]. | |
| [[has_unchanged_files]] | |
| ==== has:unchanged-files | |
| Matches when the new patch-set has the same list of files as the | |
| previous patch-set. | |
| Votes are not copied in the following cases: | |
| * If one more files are renamed in the new patch set. These files are counted | |
| as a deletion of the file at the old path and an addition of the file at the | |
| new path. This means the list of files did change. | |
| * If one or more files are reverted to their original content, that is files | |
| that become same as in the base revision. | |
| This predicate is useful if you don't want to trigger CI or human | |
| verification again if the list of files didn't change. | |
| Note, "unchanged-files" is the only value that is supported for the | |
| "has" operator. | |
| [[group-id]] | |
| ==== Group ID | |
| Some predicates (link:#approverin[approverin], link:#uploaderin[uploaderin]) | |
| expect a group ID as value. This group ID can be any of the | |
| link:rest-api-groups.html#group-id[group identifiers] that are supported in the | |
| REST API: group UUID, group ID (for Gerrit internal groups only) and group name | |
| It's preferred to reference groups by UUID, rather than name. Referencing | |
| groups by name is not recommended because: | |
| * Groups may be renamed and then the group reference can no longer be resolved. | |
| If this happens another group with different members can take over the group | |
| name, so that exemptions which have been granted by this predicate apply to | |
| the other group. This is a security concern. | |
| * Group names that contain spaces are not supported. | |
| * Ambiguous group names cannot be resolved. This means if another group with | |
| the same name gets created at a later point in time, the group name can no | |
| longer be resolved and the predicate breaks. | |
| Using the group UUID has a small drawback though, since it makes the condition | |
| less human-readable. | |
| ==== Example | |
| ---- | |
| copyCondition = is:MIN OR -change-kind:REWORK OR uploaderin:dead...beef | |
| ---- | |
| [[label_canOverride]] | |
| === `label.Label-Name.canOverride` | |
| If false, the label cannot be overridden by child projects. Any | |
| configuration for this label in child projects will be ignored. Defaults | |
| to true. | |
| [[label_branch]] | |
| === `label.Label-Name.branch` | |
| By default a given project's label applicable scope is all changes | |
| on all branches of this project and its child projects. | |
| Label's applicable scope can be branch specific via configuration. | |
| E.g. create a label `Video-Qualify` on parent project and configure | |
| the `branch` as: | |
| ---- | |
| [label "Video-Qualify"] | |
| branch = refs/heads/video-1.0/* | |
| branch = refs/heads/video-1.1/Kino | |
| ---- | |
| Then *only* changes in above branch scope of parent project and child | |
| projects will be affected by `Video-Qualify`. | |
| [NOTE] | |
| The `branch` is independent from the branch scope defined in `access` | |
| parts in `project.config` file. That means from the UI a user can always | |
| assign permissions for that label on a branch, but this permission is then | |
| ignored if the label doesn't apply for that branch. | |
| Additionally, the `branch` modifier has no effect when the submit rule | |
| is customized in the rules.pl of the project or inherited from parent projects. | |
| Branch can be a ref pattern similar to what is documented | |
| link:access-control.html#reference[here], but must not contain `${username}` or | |
| `${shardeduserid}`. | |
| [[label_ignoreSelfApproval]] | |
| === `label.Label-Name.ignoreSelfApproval (deprecated)` | |
| If true, the label may be voted on by the uploader of the latest patch set, | |
| but their approval does not make a change submittable. Instead, a | |
| non-uploader who has the right to vote has to approve the change. | |
| Defaults to false. | |
| The `ignoreSelfApproval` attribute is **deprecated**, favour | |
| using link:config-submit-requirements.html[submit requirements] and | |
| define the `submittableIf` expression with the `label` operator and | |
| the `user=non_uploader` argument. See the | |
| link:config-submit-requirements.html#code-review-example[Code Review] submit | |
| requirement example. | |
| [[label_example]] | |
| === Example | |
| To define a new 3-valued category that behaves exactly like `Verified`, | |
| but has different names/labels: | |
| ---- | |
| [label "Copyright-Check"] | |
| function = MaxWithBlock | |
| value = -1 Do not have copyright | |
| value = 0 No score | |
| value = +1 Copyright clear | |
| ---- | |
| The new column will appear at the end of the table, and `-1 Do not have | |
| copyright` will block submit, while `+1 Copyright clear` is required to | |
| enable submit. | |
| === Default Value Example | |
| This example attempts to describe how a label default value works with the | |
| user permissions. Assume the configuration below. | |
| ---- | |
| [access "refs/heads/*"] | |
| label-Snarky-Review = -3..+3 group Administrators | |
| label-Snarky-Review = -2..+2 group Project Owners | |
| label-Snarky-Review = -1..+1 group Registered Users | |
| [label "Snarky-Review"] | |
| value = -3 Ohh, hell no! | |
| value = -2 Hmm, I'm not a fan | |
| value = -1 I'm not sure I like this | |
| value = 0 No score | |
| value = +1 I like, but need another to like it as well | |
| value = +2 Hmm, this is pretty nice | |
| value = +3 Ohh, hell yes! | |
| defaultValue = -3 | |
| ---- | |
| Upon clicking the Reply button: | |
| * Administrators have all scores (-3..+3) available, -3 is set as the default. | |
| * Project Owners have limited scores (-2..+2) available, -2 is set as the default. | |
| * Registered Users have limited scores (-1..+1) available, -1 is set as the default. | |
| === Patch Set Lock Example | |
| This example shows how a label can be configured to have a standard patch set lock. | |
| ---- | |
| [access "refs/heads/*"] | |
| label-Patch-Set-Lock = +0..+1 group Administrators | |
| [label "Patch-Set-Lock"] | |
| function = PatchSetLock | |
| value = 0 Patch Set Unlocked | |
| value = +1 Patch Set Locked | |
| defaultValue = 0 | |
| ---- | |
| GERRIT | |
| ------ | |
| Part of link:index.html[Gerrit Code Review] | |
| SEARCHBOX | |
| --------- |