Reviews

This scenario will focus on how general reviews of artifacts can be modelled with external change management systems

Example:

Bob the coder initiates a code review. He assigns Joe, Rob and Jacky as reviewers. The review is tracked as a Task in their change management system, along with the assigned reviews for Joe, Rob and Jacky. As Joe, Rob and Jacky find issues, their comments are stored as Tasks and assigned back to Bob automatically. Bob does the work on each review item and marks them as resolved and creates a new change set to hold the updated code and adds this to the review. Some of the suggestions are longer term, so Bob creates other tasks or defects for those items and links them back to the review items but still marks those review items as resolved (or "future" or something that lets him still close the review). Joe, Rob and Jacky review the updates and sign off on them, marking each of them completed and then mark their assigned reviews completed. Bob can then close the review.

Scenario

Definitions

• Review - A top level change management item that is the basis for the review
• Assigned-Review - The change management item that is assigned to the reviewers to act on. These should be in the same repository as a Review.
• Review-Item - Each suggested change from a user performing work on an Assigned-Review is represented by a change management item in the same or another repository.
• Reviewee - The person who owns the artifact being reviewed.
• Reviewer - The person who is actually reviewing the artifact.

Pre-conditions

• A change management repository exists for Review, Assigned-Review
• A change management repository exists for Review-Item (this can be the same repository as for Review / Assigned-Review).
• A Review type exists and a workflow is defined for reviews. The workflow has at least states defining incomplete and a complete states.
• The review change management capability is enabled.
• All integrated change management tools are OSLC CM 2.0 providers.
• Cross-server communication is established.

Post-conditions

• The Review is in a completed state
• Each Assigned-Review is in a completed state and assigned as a child to the parent Review.
• Each Review-Item is in a completed state and assigned as children to the parent Assigned-Review.

Steps

(Step 1) A Review is initiated

1. The review workflow is started and a Review change management item is created and assigned to the artifact owner. (It need not be the artifact owner who initiates the review)
2. The artifact to be reviewed is identified and associated to the Review, either as an attachment or linked by some means.
3. Reviewers are assigned to the review and the workflow creates an Assigned-Review for each reviewer.
4. Reviewers are notified they have a new Assigned-Review.

(Step 2) Reviewers: Perform the review on the designated artifact

1. Each reviewer gets the Assigned-Review assigned to them and they perform the work by opening up the artifact.
2. Each reviewer suggests changes to the Review and each suggestion is captured into a Review-Item in the designated repository. (The designated repository would be defined by preferences of that system. Ex: Track code review suggested changes as bugs, document suggested changes as Tasks, etc)
   • Include information required like file, lineno, document, section, etc. Ideally this would be put in by the IDE automatically into some field of the Review-Item that could be used later by the IDE to better visualize the suggested change.
3. Each Review-Item is set to be a child of the Assigned-Review by the workflow

(Step 3) Reviewee: Processes each suggestion

1. The reviewee processes each Review-Item and either does the work or reassigns it to someone else.
2. When the work is done on each Review-Item, the status is changed to resolved.
3. [Optional] A new artifact with the changes may be associated to the review items at this point.

(Step 4) Reviewer: Review the changes

1. The reviewer processes each resolved Review-Item and approves them (marking them complete) or makes more comments and reopens them.
2. When each Review-Item is completed [Optional], the Assigned-Review is marked as complete by the reviewer.
   • Note: It could be enforced that an Assigned-Review cannot be considered complete until all Review-Items are complete but some systems may want to log defects in their system to track the changes yet still consider the review complete.

(Step 5) Reviewee: Close the Review

1. The reviewer can mark the Review complete when all Assigned-Review s are marked complete.

1) -- DenisTyrell - 09 Dec 2009