Review process

These review processes describe how reviews are created, updated, shared, and maintained.

Use these processes to:

  • Create reviews from changelists.

  • Update reviews.

  • Collaborate with other contributors.

  • Manage reviews using review keywords.

  • Repair or rebuild reviews when required.

To learn more about approval requirements, see Approval rules.

Basic review workflow

The most common review process involves:

  1. Creating a review.

  2. Requesting feedback.

  3. Updating the review in response to comments.

  4. Obtaining approval.

  5. Committing the changes.

For examples from both the review author and reviewer perspectives, see:

Start a review from P4 Code Review

To start a review from P4 Code Review:

  1. Open a shelved or submitted changelist.

  2. Select Request Review.

A review is created from the changelist.

Update a pre-commit review

To update a pre-commit review:

  1. Modify the files.

  2. Shelve the files.

P4 Code Review updates the review automatically.

To learn more about review versions, see Review versions.

If you do not want review updates to be applied automatically, add the work-in-progress tag to the changelist description.

For an example of a review author responding to feedback and updating a review, see Another developer reviews your code.

Collaborative reviews

Reviews can be updated by multiple contributors.

Collaborative reviews allow multiple users to contribute changes, respond to feedback, and update review content.

Update an existing review

To update an existing review:

  1. Fetch the review files.

  2. Modify the files.

  3. Add the review identifier to the changelist description: #review-12345

  4. Shelve the files.

When the files are shelved, P4 Code Review updates review 12345.

To learn more about review identifiers and review keywords, see Review keywords.

If the review identifier is invalid, the review is not updated.

For an example of another contributor updating an existing review, see Advanced review process using #review and #append in the changelist description.

Multiple contributors

P4 Code Review allows multiple contributors to work on the same review.

Contributors can:

  • Update existing review content.

  • Append additional changelists.

  • Replace review content.

  • Repair review content.

For examples of multiple contributors updating the same review, see:

Review keywords

Review keywords are added to changelist descriptions to create or update reviews.

#review

Use #review to create a review when shelving or submitting a changelist.

To create a review:

  1. Add the following keyword to the changelist description: #review

  2. Then shelve or submit the changelist.

After the review is created, P4 Code Review replaces #review with #review-12345, where 12345 is the review identifier.

If you shelve a changelist and then afterwards add #review a review is NOT started. You must reshelve the files and update the changelist with the #review tag.

For an example of creating a review using the #review keyword, see Basic review process using #review and #append in the changelist description

Add reviewers during review creation

Reviewers can be added during review creation.

  • To add a user, add @userid

  • To add a group, add @@groupid

Required reviewers can also be specified when the review is created.

  • To make the specified user a required reviewer, use: @*userid

  • To make all members of the group required reviewers, use: @@*groupid

  • To make the group a required reviewer, but only one member of the group must vote, use: @@!groupid

To learn more about reviewers, required reviewers, and approval requirements, see:

#review-xxxxx

Use #review-xxxxx to update an existing review.

Example: #review-12345

The changelist is added to review 12345 when the files are shelved.

To learn more about review content updates, see Review content.

When used to update a review, the changelist replaces the current review content unless append or replace keywords are used explicitly.

For an example of updating an existing review using a review identifier, see Advanced review process using #review and #append in the changelist description

#append-xxxxx

Use #append-xxxxx to add the contents of a changelist to an existing review.

To append a changelist to an existing review:

  1. Add the following keyword to the changelist description: #append-12345

  2. Shelve the changelist.

The changelist content is appended to the existing review content (review 12345) rather than replacing it.

To learn more about append mode, see Append mode.

For examples of append mode behavior, see:

#replace-xxxxx

Use #replace-xxxxx to replace the contents of an existing review.

To replace review content:

  1. Add the following keyword to the changelist description: #replace-12345

  2. Shelve the changelist.

The existing review content is replaced by the changelist content.

To learn more about replace mode, see Replace mode.

For an example of replace mode behavior, see Advanced review process using #review, #append, and #replace in the changelist description

Advanced review processes

Advanced review processes provide additional control over review content.

Revert review content

Reverting a review creates a new review version. The review content matches the selected version, but the review version number is incremented.

To restore the contents of an earlier review version:

  1. Use the review version selector to identify the changelist associated with the review version you want to restore.

  2. Unshelve the files.

  3. Create a new changelist.

  4. Shelve the files.

  5. Open the review.

  6. Select Review Actions > Add Change.

  7. Select Replace with pending changelist.

  8. Select the changelist.

After reverting a review, consider updating the review description or adding a comment to explain why the review content was restored.

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

Repair a review

To repair a review using a new changelist:

  1. Create or update the changelist that contains the correct content.

  2. Update the review keyword in the changelist description.

For example:

  1. Change #review-12345

  2. To either:

    • #append-12345

    • #replace-12345

  3. Shelve the files.

The review is updated using the selected keyword.

To learn more about append mode and replace mode, see:

For an example of repairing a review after it has been updated incorrectly, see Fix a review if it has been replaced with the wrong changelist.

Work-in-progress reviews

If a review is still being developed, add the work-in-progress tag (#wip by default) to the changelist description.

The work-in-progress tag prevents P4 Code Review from updating the review until the tag is removed and the files are shelved again.

To learn more, see Work-in-progress tag.

Next steps