Reviewing models and designs

A review is a process to help gather feedback from team members on a set of artifacts.

About this task

A review follows a lifecycle and passes through several states as participants complete their work by the assigned due date. Participants can check the status of a review, provide comments, and review on artifacts. During the review lifecycle, the review author can update artifacts, add participants and change participant roles as needed.

There are two types of participant roles:
  • Subscribers can track the status of a review, but do not have review assignments. When the author changes the state of the review, subscribers are notified by email.
  • Reviewers are assigned to review a artifact or collection of artifacts by an assigned due date. Reviewers must complete their assignment and review all artifacts before the review is considered finished. Reviewers also receive email notification on the status of a review.
  • Approvers are assigned to approve a artifact or collection of artifacts by an assigned due date. Approver must complete their assignment and approve or reject all artifacts before the review is considered finished. Approvers also receive email notification on the status of a review.

After all participants have reviewed the artifacts, the review is automatically moved to the Reviewed state. The author can then finalize the review, and can provide a summary of the review results. This review summary is automatically sent by email to all the review participants: both Reviewers and Subscribers.

There are three types of reviews: formal, informal, and change set.

  • Formal reviews are associated with a project baseline, which contains a controlled, static version of artifacts.
  • Informal reviews are associated with a stream; they are useful when you want to gather feedback on a set of artifacts quickly. Any artifact modifications in the stream are reflected in the review because the review is associated with a stream. The review author can reset artifact feedback if there are major changes made to the artifact, therefore notifying the reviewers that they must review a new version of the artifact.
  • Change set reviews are associated with artifacts that reside inside change sets. In a change set review, the author cannot add or remove artifacts. The only artifacts that reside in a change set review are a part of a change set.

The state of the review changes throughout its lifecycle.

Review state Description
Draft The author creates the review by adding participants and artifacts, and assigning roles and due dates. Participants are not notified when the review is in the draft state.
In Progress The author clicks Start Review. Participants join the review and begin their work assignments. All reviews must have at least one reviewer and one artifact, and participants are notified by email that a review has started.
Paused If a review author needs to modify a review, the author clicks Pause Review to update the list of participants, change participant roles, and add or modify artifacts. While the review is paused, the review author can also update the list of participants, change participant roles, add or modify artifacts, and reset the status of a artifact, which forces reviewers to perform a new review of the artifact. Participants cannot mark artifacts as reviewed until the review author continues the review.
Reviewed When all the reviewers have reviewed on their assigned artifacts, the review is moved to the Reviewed state. Reviewers can still update their results and add additional comments, but the review can no longer be modified.
Finalized The author clicks Finalize Review. While finalizing a review, the review author can provide a summary of the review outcome; this summary is sent to participants and is saved with the review. When a review is finalized, the review is saved and cannot be modified by the author; however, reviewers can still comment and add links.

Feedback