States // Swarm 2014.1: User Guide

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

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 Approve and Commit button, the review becomes approved and its associated files are committed.

The Commit Review dialog

Note

This option can be removed by an administrator. See “Disable commit” 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 Already Committed... displays a dialog presenting a list of candidate changelists:

The Select Change dialog

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 Select 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 Add a commit... entry in place of Already Committed.... Select Add a commit... to use the Select Change dialog as described above.