Review (CMMI)

In this topic, you can learn how to fill in the details of a review work item. A team can use the review work item to document the results of a design or code review. Team members can capture the details of how the design or code meets standards in areas of name correctness, code relevance, extensibility, code complexity, algorithmic complexity, and code security. For more information, see Implementing Development Tasks.

For information about how to create this type of work item, see Work Items and Workflow (CMMI).

In this topic	Related topics
Defining a Review Linking a Review to a Requirement, Task, or Other Work Item Adding Details, Attachments, or Hyperlinks to a Review Changing the State of a Review	Process Guidance Implementing Development Tasks Field Reference Review Meeting Fields (CMMI) Titles, IDs, Description, and History (CMMI) Areas and Iterations Assignments, Workflow, and Planning (CMMI) Linking Work Items (CMMI) Attachments

Required Permissions

To view a review, you must be a member of the Readers group or your View work items in this node must be set to Allow. To modify a review, you must be a member of the Contributors group or your Edit work items in this node permissions must be set to Allow. For more information, see Managing Permissions.

Defining a Review

The work item form for a review stores data in the fields and tabs that the following illustrations show:

   

When you define a review, you must define the Title in the top section of the work item form and the Purpose on the Details tab. You can leave all other fields blank or accept their default values.

To define a single review

1. In the top section of the work item form, specify one or more of the following types of information:

   • In Title (Required), type a short description that distinguishes this review from other review work items.

     Good titles identify the section of code or design area that was reviewed.

   • In the Meeting Type list, click the type of meeting that was used for the review.

     Valid values are Meeting or Offline.

   • In the Assigned To list, click the name of the team member who is responsible for addressing the review.

     Note

     You can assign work items only to members of the Contributors group.

     If you leave the review unassigned, it is automatically assigned to you.

   • In the State list, leave the default value, Active.

   • In the Facilitators section, click the name of the team member who called the meeting, and type the date of the meeting.

2. On the Details tab, provide as much detail as you want to describe the area of code or design that was reviewed, in addition to the criteria that was applied in the review.

3. On the Minutes tab, provide as much detail as you want to describe the results, discussion, criteria, and decisions that resulted from the review meeting.

   This information might include what was reviewed, the criteria that was applied, and the problems that were identified.

4. On the Comments tab, type any miscellaneous information about the review that is not appropriately captured elsewhere.

5. On the Attendees tab, click the name of each team member that is a required, optional, or actual attendee of the review.

   These team members are members of the review board.

6. On the All Links tab, link the review to one or more other work items, such as a requirement or task.

7. On the Attachments tab, attach specifications, images, or other files that provide more details about the review to be held.

   For more information, see the following sections later in this topic:

   • Linking a Review to a Requirement, Task, or Other Work Item

   • Adding Details, Attachments, or Hyperlinks to a Review

8. Click Save Work Item.

   Note

   After you save the review, the identifier appears in the title under the work item toolbar.

Linking a Review to a Requirement, Task, or Other Work Item

You use the Links tab to create links to specific types of work items and for specific types of links. For more information, see Linking Work Items (CMMI).

To create and link a task, requirement, or other work item to a review

1. Open the form for the review work item, click the All Links tab, and then click New.

   The Add new Linked Work Item dialog box opens.

   

2. In the Link Type list, click Related or another type of link that represents the relationship that you want to track.

3. In the Work Item Type list, click the type of work item that you want to create.

4. In Title, type a short but specific description.

5. (Optional) In Comment, type additional information.

6. Click OK.

   A form for the type of work item that you specified opens with the information that you have provided.

7. Specify the remaining fields as the following topics describe:

   • Requirement (CMMI)

   • Change Request (CMMI)

   • Task (CMMI)

   • Bug (CMMI)

   • Test Case (Agile)

   • Issue (CMMI)

8. Click Save Work Item.

To link one or more existing work items to a review

1. Open the form for the review work item, click the All Links tab, and then click Link to.

   The Add Link to Review dialog box opens.

   

2. In the Link Type list, click Related or another type of link that represents the relationship that you want to track based on the type of work item to which you are linking.

3. Perform one of the following actions:

   • In Work item IDs, type the IDs of the work items that you want to find. Separate IDs by commas or spaces.

   • Click Browse to specify work items from a list.

     The Choose linked work items dialog box appears.

     

     In the Saved query list, click a query that contains the work items that you want to add. For example, you can click Open Work Items, Active Bugs, or Active Tasks.

     Click Find, select the check box next to each work item that you want to link to the issue, and then click OK.

   • (Optional) Type a description for the items to which you are linking.

4. Click OK.

   For more information, see Find Work Items to Link or Import.

5. Click Save Work Item.

   Note

   Both the review and work items to which you linked are updated.

Adding Details, Attachments, or Hyperlinks to a Review

As more information becomes available, you can add information to a review in the following ways:

• Type information in the boxes on the Details, Minutes, or Comments tabs.

• Attach a file.

  For example, you can attach an e-mail thread, a document, an image, a log file, or another type of file.

• Add a hyperlink to a Web site or to a file that is stored on a server or Web site.

To add details to a review

1. Click the Details, Minutes, or Comments tab, and type information in the boxes.

   You can format information to provide emphasis or capture a bulleted list.

   Note

   Every time that a team member updates the work item, its history shows the date of the change, the name of the team member who made the change, and the fields that changed.

   For more information, see Review Meeting Fields (CMMI) and Titles, IDs, Descriptions, and History (Agile).

2. Click Save Work Item.

To add an attachment to a review

1. On the Attachments tab, perform one of the following actions:

   • Drag a file into the attachment area.

   • Click or press CTRL-V to paste a file that you have copied.

   • Click Add, click Browse, and, in the Attachment dialog box, type or browse to the name of the file that you want to attach.

     (Optional) In the Comment box, type additional information about the attachment. To close the Attachment dialog box, click OK.

2. Click Save Work Item.

To add a hyperlink to a review

1. On the All Links tab, click Link to.

   

2. In the Link Type list, click Hyperlink.

3. In the Address box, perform one of the following actions:

   • If the target is a Web site, type the URL, or copy it from your Internet browser and paste it into the Address box.

   • If the target is a server location, type its UNC address.

4. (Optional) In the Comment box, type additional information about the hyperlink.

5. Click OK.

6. Click Save Work Item.

Changing the State of a Review

If the review finds that the design or code needs no changes, the review work item can be closed. If the design or code needs minor or major changes, the active review work item is assigned to a developer to resolve. If only minor changes are needed, the developer can close the review work item. If major changes are needed, a second review is required, and the review work item is closed only if the second review passes successfully.

Team members can use the following states to track the progress of reviews:

• Active

• Resolved

• Closed

You create a review in the Active state.

For more information about the data fields that you can use to track work item states, see Assignments, Workflow, and Planning (CMMI).

To change the state of a review

1. Open the review work item.

2. In the State list, click Resolved or Closed.

   • If you change the state from Active to Resolved, the Reason field automatically changes to Accepted with Minor Changes.

   • If you change the state from Resolved to Closed, the Reason field changes to Minor Changes Complete.

3. Click Save Work Item.

Typical workflow progression: A team member creates a review in the Active state with the default reason, New. A team member changes the state of the review from Active to Resolved when the review board determines that the code is acceptable if minor changes are made. A team member changes the state from Resolved to Closed after any required changes have been made. Atypical transitions: A team member changes the state from Active to Closed with the default reason, Accepted (as is). The review board determines that major changes to the code must be made and changes the state from Resolved to Active. A team member determines that the review was closed in error and changes the state from Closed to Active.

Review State Diagram

Active (New)

An active review work item documents the results of a design or code review. Attendees of the review meeting determine what the next steps should be. The review work item is closed if no changes are necessary. It remains active and is assigned to the appropriate developer if changes are required. The developer resolves the review work item after the changes are completed.

From Active to Resolved

A team member can resolve an active review for the reasons in the following table:

Reason	When to use	Additional actions to take
Accepted with Minor Changes	When the developer has completed the identified changes in the design or code.	None.
Accepted with Major Changes	When the developer has completed the identified changes in the design or code.	Reactivate the review work item.

The following data fields are captured when a team member resolves an active review:

• Resolved By: Name of the team member who resolved the review.

• Resolved Date: Date and time when the review was resolved, as recorded by the server clock.

• State Change Date: Date and time when the state of the review was changed.

From Active to Closed

A team member can close an active review when the review board decides, for whatever reason, that no changes are required. The Reason field is automatically set to Accepted (As Is).

The following data fields are captured when a team member closes an active review:

• Closed By: Name of the team member who closed the review.

• Closed Date: Date and time when the review was closed, as recorded by the server clock.

• State Change Date: Date and time when the state of the review was changed.

Resolved

A resolved review work item indicates that the required changes, whether minor or major, have been completed. If the changes were major, a second review is required before the review work item can be closed. If the second review uncovers additional changes, the review work item is reactivated.

From Resolved to Closed

A team member can close a resolved review for the reason in the following table:

Reason	When to use	Additional actions to take
Minor Changes Complete	When minor changes have been identified, made, and verified.	Assign the review to the product owner.

The following data fields are automatically captured when a team member closes a resolved review:

• Closed By: Name of the team member who closed the review.

• Closed Date: Date and time when the review was closed, as recorded by the server clock.

• State Change Date: Date and time when the state of the review was changed.

From Resolved to Active

You can reactivate a resolved review for the reason in the following table:

Reason	When to use	Additional actions to take
Major Changes Complete	When a second review is required to determine whether any problems remain.	Call another review meeting to verify the code that changed.

The following data is automatically captured when a team member reactivates a resolved review:

• Activated By: Name of the team member who reactivated the review.

• Activated Date: Date and time when the review was reactivated, as recorded by the server clock.

• State Change Date: Date and time when the state of the review was changed.

Closed

A closed review is no longer being worked on but can be reactivated if it comes back into scope. Usually a business analyst or program manager reactivates a closed review.

From Closed to Active

A closed review work item indicates that the review is complete and any necessary changes have been completed. You can reactivate a closed review if it was accidentally closed. The reason for the reactivation is set to Closed in error.

The following data is automatically captured when a team member reactivates a closed review:

• Activated By: Name of the team member who reactivated the review.

• Activated Date: Date and time when the review was reactivated, as recorded by the server clock.

• State Change Date: Date and time when the state of the review was changed.

See Also

Concepts

Review Meeting Fields (CMMI)

Task (CMMI)

MSF for CMMI Process Improvement v5.0

Other Resources

Work Items and Workflow (CMMI)