2474e52beb
Currently the labels look like a direct suggestion to a maintainer dealing with the change, but even being interpreted this way, -1 label sounds strange as "didn't submit" doesn't match the fact nobody has submitted anything yet. What's worse, new contributors have every right to assume that the message is addressing them, and upon receiving an email saying "I would prefer you didn't submit this" they mistakenly think that the word "submit" refers to their action of posting for review, there's nothing to indicate this part is directed to the maintainer. Also, most people have never seen the "Submit" button, that's a process detail known to the maintainers but not the general public. This is confirmed by real-life observations of contributors to the OpenOCD project, I know at least three persons who got somewhat offended by receiving such a message from the review system. Change-Id: I035a615a6caf6e085edd5827f3bfe33342156324 Signed-off-by: Paul Fertser <fercerpav@gmail.com>
306 lines
10 KiB
Plaintext
306 lines
10 KiB
Plaintext
= 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.
|
|
|
|
|
|
[[label_Code-Review]]
|
|
== Label: Code-Review
|
|
|
|
The code review label is the second of two default labels that 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 merged
|
|
+
|
|
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 merged 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 Do not submit`. 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.
|
|
|
|
Administrators can install the Verified label by adding the following
|
|
text to `project.config`:
|
|
|
|
====
|
|
[label "Verified"]
|
|
function = MaxWithBlock
|
|
value = -1 Fails
|
|
value = 0 No score
|
|
value = +1 Verified
|
|
====
|
|
|
|
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]]
|
|
== Your Label Here
|
|
|
|
Site administrators and project owners can also define their own labels.
|
|
|
|
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`. 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. To remove a label in a child project, add an
|
|
empty label with the same name as in the parent.
|
|
|
|
Labels are laid out in the order they are specified in project.config,
|
|
with inherited labels appearing first, providing some layout control to
|
|
the administrator.
|
|
|
|
[[label_name]]
|
|
=== `label.Label-Name`
|
|
|
|
The name for a label, consisting only of alphanumeric characters and
|
|
`-`.
|
|
|
|
|
|
[[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_abbreviation]]
|
|
=== `label.Label-Name.abbreviation`
|
|
|
|
An abbreviated name for a label shown as a compact column header, for
|
|
example on project dashboards. Defaults to all the uppercase characters
|
|
in the label name, e.g. `Label-Name` is abbreviated by default as `LN`.
|
|
|
|
|
|
[[label_function]]
|
|
=== `label.Label-Name.function`
|
|
|
|
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 lowest possible negative value, if present, blocks a submit, Any
|
|
other value enables 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.
|
|
|
|
|
|
[[label_copyMinScore]]
|
|
=== `label.Label-Name.copyMinScore`
|
|
|
|
If true, the lowest possible negative value for the label is copied
|
|
forward when a new patch set is uploaded.
|
|
|
|
[[label_copyMaxScore]]
|
|
=== `label.Label-Name.copyMaxScore`
|
|
|
|
If true, the highest possible positive value for the label is copied
|
|
forward when a new patch set is uploaded. This can be used to enable
|
|
sticky approvals, reducing turn-around for trivial cleanups prior to
|
|
submitting a change.
|
|
|
|
[[label_copyAllScoresOnTrivialRebase]]
|
|
=== `label.Label-Name.copyAllScoresOnTrivialRebase`
|
|
|
|
If true, all scores for the label are copied forward when a new patch
|
|
set is uploaded that is a trivial rebase. A new patch set is considered
|
|
as trivial rebase if the commit message is the same as in the previous
|
|
patch set and if it has the same code delta as the previous patch set.
|
|
This is the case if the change was rebased onto a different parent.
|
|
This can be used to enable sticky approvals, reducing turn-around for
|
|
trivial rebases prior to submitting a change. Defaults to false.
|
|
|
|
[[label_copyAllScoresIfNoCodeChange]]
|
|
=== `label.Label-Name.copyAllScoresIfNoCodeChange`
|
|
|
|
If true, all scores for the label are copied forward when a new patch
|
|
set is uploaded that has the same parent commit as the previous patch
|
|
set and the same code delta as the previous patch set. This means only
|
|
the commit message is different. This 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.
|
|
Defaults to false.
|
|
|
|
[[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.
|
|
|
|
[[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.
|
|
|
|
GERRIT
|
|
------
|
|
Part of link:index.html[Gerrit Code Review]
|
|
|
|
SEARCHBOX
|
|
---------
|