Review process examples

The examples on this page demonstrate common review scenarios and show how review processes and review keywords work in practice.

Unlike the Review process page, which describes individual features and procedures, these examples show complete end-to-end scenarios, including review creation, review updates, collaboration between contributors, append and replace operations, and review recovery.

Use these examples to understand how review content changes over time, how multiple contributors can work on the same review, and how review keywords such as #review, #append-xxxx, and #replace-xxxx affect review behavior.

Another developer reviews your code

This example shows a typical review process in which a reviewer provides feedback, the review author updates the review, and the review is approved and committed.

1. Create a review from a shelved changelist.

2. A reviewer opens the review, examines the file diffs, and adds a comment requesting clarification or feedback on a specific change.

3. The review author receives the comment notification, updates the code to address the feedback, and updates the review with the revised files.

4. The reviewer examines the updated review and, if the changes are satisfactory, changes the review state to Approved.

5. After the review is approved, the review author commits the changes.

This review cycle can be repeated as many times as required until all feedback has been addressed and the review is approved.

You review the code from another developer

This example demonstrates how reviewers and authors can collaborate through comments, tasks, review updates, and review state changes.

1. A developer creates a review from a shelved changelist.

2. A reviewer examines the review, identifies issues with the implementation, adds comments, flags the comments as tasks, and changes the review state to Needs revision.

3. The review author responds to the feedback by adding comments that explain or justify the implementation.

4. Rather than continuing the discussion in comments, the reviewer fetches the review files, updates the code, and shelves the changes. P4 Code Review updates the review with the revised implementation.

5. The review author evaluates the updated implementation by fetching the review files into a local workspace. After reviewing the changes, the author makes additional improvements and shelves the updated files to create a new review version.

6. The reviewer examines the latest review version and determines that the review is no longer required. The reviewer adds a comment explaining the reason and changes the review state to Rejected.

This example demonstrates that review participants can collaborate by:

• Adding comments and tasks.

• Requesting revisions.

• Responding to review feedback.

• Updating review content.

• Creating additional review versions.

• Changing the review state when the review is no longer required.

Basic review process using #review and #append in the changelist description

This example demonstrates how review content changes when multiple contributors use #review and #append keywords to update the same review.

1. Create a review containing:

   • A^#1

   • B^#1

   • C^#1

   using #review in the changelist description.

2. P4 Code Review creates review xxxx and replaces #review with #review-xxxx in the changelist description.

3. A second contributor creates a changelist containing:

   • C^#2

   • D^#1

   • E^#1

   and appends the changelist to review xxxx using #append-xxxx.

4. Review xxxx now contains:

   • A^#1

   • B^#1

   • C^#2

   • D^#1

   • E^#1

5. Because the review was updated using #append-xxxx, the default add mode for review xxxx is now append.

6. Update files:

   • A^#1 to A^#2

   • B^#1 to B^#2

   The changelist description still contains #review-xxxx.

7. Shelve the changelist.

8. Because the review is operating in append mode, the changelist is appended to the review even though the changelist description contains #review-xxxx.

   The review add mode is stored with the review, not with the changelist. To learn more about add modes, see Append mode and Replace mode.

9. Review xxxx now contains:

   • A^#2

   • B^#2

   • C^#2

   • D^#1

   • E^#1

This example demonstrates that the review's current add mode determines how subsequent updates using #review-xxxx are processed.

After a review has been updated using #append-xxxx, later updates using #review-xxxx are also appended unless the add mode is changed.

Advanced review process using #review and #append in the changelist description

This example demonstrates how multiple contributors can update the same review and how the review's add mode affects future updates.

1. Create a review containing:

   • A^#1

   • B^#1

   using #review in the changelist description.

2. P4 Code Review creates review xxxx and replaces #review with #review-xxxx in the changelist description.

3. A second contributor creates a changelist containing:

   • C^#1

   and appends the changelist to review xxxx using #append-xxxx.

4. Review xxxx now contains:

   • A^#1

   • B^#1

   • C^#1

5. Because the review was updated using #append-xxxx, the default add mode for review xxxx is now append.

6. A third contributor creates a changelist containing:

   • A^#2

   • D^#1

   and updates review xxxx using #review-xxxx.

   Because the review is operating in append mode, the changelist is appended to the review.

7. Review xxxx now contains:

   • A^#2

   • B^#1

   • C^#1

   • D^#1

8. Update:

   • A^#2 to A^#3

   • B^#1 to B^#2

   and add:

   • E^#1

   The changelist description still contains: #review-xxxx

9. Shelve the changelist.

10. Because the review is operating in append mode, the changelist is appended to the review.

11. Review xxxx now contains:

    • A^#3

    • B^#2

    • C^#1

    • D^#1

    • E^#1

This example demonstrates that:

• Multiple contributors can update the same review.

• The review add mode persists between updates.

• After a review has been switched to append mode, updates using #review-xxxx are appended to the review.

• Later file revisions replace earlier revisions of the same file within the review.

Advanced review process using #review, #append, and #replace in the changelist description

This example demonstrates how a review can move between append mode and replace mode, and how the current add mode affects subsequent review updates.

1. Create a review containing:

   • A^#1

   • B^#1

   using #review in the changelist description.

2. P4 Code Review creates review xxxx and replaces #review with #review-xxxx in the changelist description.

3. A second contributor creates a changelist containing:

   • C^#1

   and appends the changelist to review xxxx using #append-xxxx.

4. Review xxxx now contains:

   • A^#1

   • B^#1

   • C^#1

5. Because the review was updated using #append-xxxx, the default add mode for review xxxx is now append.

6. A third contributor creates a changelist containing:

   • A^#2

   • D^#1

   and replaces the review content using #replace-xxxx.

7. Review xxxx now contains:

   • A^#2

   • D^#1

8. Because the review was updated using #replace-xxxx, the default add mode for review xxxx is now replace.

9. Update:

   • A^#2 to A^#3

   • B^#1 to B^#2

   and add:

   • E^#1

   The changelist description still contains #review-xxxx.

10. Shelve the changelist.

11. Because the review is operating in replace mode, the review content is replaced even though the changelist description contains #review-xxxx.

12. Review xxxx now contains:

    • A^#3

    • B^#2

    • E^#1

This example demonstrates that:

• Reviews can switch between append mode and replace mode.

• The most recent add mode becomes the default add mode for the review. To learn more about add modes, see Append mode and Replace mode.

• Updates using #review-xxxx follow the current review add mode.

• When a review is operating in replace mode, existing review content can be removed and replaced by newer changelists.

• The review add mode should be considered when multiple contributors update the same review.

Fix a review if it has been replaced with the wrong changelist

If a review has been updated with the wrong changelist, the review can be repaired so that it contains the intended files.

To learn more about review versions and version history, see:

• Review versions

• Reverting review versions

Scenario

1. Create pending changelist 250 containing files A^#1 and B^#1.

2. Create a review from changelist 250 by selecting Request Review.

3. Version 1 of review 251 is created and contains:

   • A^#1

   • B^#1

4. Open review 251, select Add Change > Replace with committed changelist, and select changelist 241.

5. Changelist 241 contains:

   • X^#1

   • Y^#1

6. The review content is replaced with the files from changelist 241.

7. Version 2 of review 251 is created and contains only:

   • X^#1

   • Y^#1

8. The review was updated incorrectly. The intended result was to append changelist 242 to review 251.

Target state

Review 251 should contain:

• A^#1 and B^#1 from changelist 250.

• C^#1 and D^#1 from changelist 242.

It is good practice to update the review description or add a comment explaining why the review content has changed.

Resolution

1. Open review 251, select Add Change > Replace with pending changelist, and select changelist 242.

2. Changelist 242 contains:

   • C^#1

   • D^#1

3. The review content is replaced with the files from changelist 242.

4. Version 3 of review 251 is created and contains:

   • C^#1

   • D^#1

5. Edit the description of changelist 250 and change: #review-251 to: #append-251

6. Shelf the files in changelist 250.

7. Changelist 250 is appended to review 251 because the review now uses append mode.

8. Version 4 of review 251 is created and contains:

   • A^#1

   • B^#1

   • C^#1

   • D^#1