States
Reviews can be in one of several states. The biggest differentiator is whether the review's files have any outstanding, uncommitted changes or not.
Whenever a review's state changes, an email notification is sent to all review participants, including the author, anyone who comments on the review or its files, anyone who has changed the review's state previously, and anyone who is @mentioned in the review's description or comments.
Code reviews can be in one of the following states:
- Needs review
-
The review has started and the changes need to be reviewed.
- Needs revisions
-
The changes have been reviewed and the reviewer has indicated that further revisions are required.
- Approved
-
The review has completed. The changes need to be committed.
Note that if an approved review is updated with modified files, the review's state automatically reverts to Needs Review. Files are considered modified if the list of involved files changes, or if the file content or file-type changes.
- Rejected
-
The review has completed. The changes are undesirable and should not be committed.
- Archived
-
The review has completed for now. However, it is neither rejected nor approved; it is simply put aside in case it is needed in the future.
Moderators
Moderators can be assigned to a project branch. Changing the state of any review associated with a moderated branch is restricted as follows:
-
Only moderators can approve or reject the review. Moderators can also transition a review to any other state.
-
The review's author can change the review's state to Needs Review, Needs Revision, Archived, and can attach committed changelists. Normally, the review's author cannot change the review's state to Approved or Rejected on moderated branches. There is one exception: if the author is the only moderator on the branch, they may approve or reject their own review.
-
Project members can change the review's state to Needs Review or Needs Revision, and can attach committed changelists. Project members cannot change the review's state to Approved, Rejected, or Archived.
-
Users that are not project members, moderators, or the review's author cannot transition the review's state.
-
For the review's author and project members, if a review is not in one of their permitted states, for example if the review's state is Rejected, they cannot transition the review to another state.
These restrictions have no effect on who can start a review.
Required reviewers
Reviews can optionally have required reviewers. When a review has required reviewers, the review cannot be Approved until all required reviewers have up-voted the review. If the review is associated with a project that has assigned moderators, even the moderators cannot approve the review without up-votes from all required reviewers (but they can reject the review).
Required reviewers are expected to take greater care while performing a review than non-required reviewers, as their votes affect whether a review can be approved or not.
To edit the reviewers for a review, and to change whether a reviewer is required or not, see “Edit reviewers”.
State actions
The drop-down menu provides two actions included with the state change for
uncommitted reviews:
- Approve and Commit
-
When selected, a dialog appears allowing you to update the description, select which jobs should be associated, and specify the job status upon commit. When you click the button, the review becomes approved and its associated files are committed. By default, Swarm's activity stream entries and email notifications note that you committed the review on behalf of the review's author. This can be configured to credit only the committer, see “Commit credit” for details.
Note
This option can be removed by an administrator. See “Disable commit” for details.
By default, if the committer is not the review's author, Swarm credits both users. If you prefer to credit only the committer, see “Commit credit” for details.
- Already Committed...
-
Sometimes, a changelist that a review is based upon gets committed without the review being updated. In such a situation, selecting displays a dialog presenting a list of candidate changelists:
Specify the changelist, if you know it, or browse the recent changes to locate the submitted change. The first field under History allows you to filter changes by depot path. The second field allows you to filter changes by userid. Click a changelist to select it, and then click to associate the changelist with the review and complete the review. Or, just double-click a changelist to do the same.
When a review has been committed, sometimes a follow-up change needs to be
associated with the review. For committed reviews, the drop-down menu
provides the entry in place of
. Select to use the Select Change
dialog as described above.