Integration with P4 Code Review

P4 Code Review is a powerful and flexible code review and collaboration solution that helps teams ship quality software. P4 Code Review enables review of code and other assets before or after commit.

P4 Code Review can be customized to fit into various workflows.

A P4 Code Review review can be for files, a stream spec, or a stream spec along with files. For example,

See also Shelve streams.

P4 Code Review stores all of its metadata (including Reviews, Projects, and Comments) in P4 Server, so it does not require backing up an external database. For more about using and installing P4 Code Review, see the P4 Code Review Documentation.

Show a submitted changelist in P4 Code Review

When P4V displays a submitted changelist, if you click the down arrow, a context-menu pops up that allows you to copy the changelist number to the Clipboard, show the changelist in P4 Code Review, or copy the P4 Code Review URL to the Clipboard.

View files in P4 Code Review from context menus

You can show a file in P4 Code Review from a context menu:

• For a file in the Workspace or Depot tab:
  
  

• When a file (or shelved file) has focus:
  

  in which case P4 Code Review shows your have revision.

View jobs in P4 Code Review from context menus

You can show a job in P4 Code Review from a context menu in the Jobs tab, the Pending Changelist tab, or the Submitted Changelist tab:

• In the Jobs tab
  
  

• In the Pending Changelist tab
  

• In the Submitted Changelist tab

  

Review workflow

Following is the happy path workflow for a P4 Code Review review. For more information, see the P4 Code Review Documentation.

1. Make local changes to files: P4 Code Review reviews can follow either a pre-commit or post-commit workflow. In both models, the author would make some local content changes to one or more files and then get those content changes into Perforce.
2. Request a review: For pre-commit code reviews, the P4 Code Review solution uses P4 Server shelving technology to get the content to P4 Server. For post-commit code reviews, content committed to P4 Server is added to a review. In both cases, a P4 Code Review review is created with an ID, a description, a set of files, and other metadata, including the author, reviewers, and comments made on the review.
3. Provide review feedback: Reviewers can comment on files or individual lines in files using P4 Code Review. They can also add follow-up tasks that the author should address before the review can be closed.
4. Request revisions: If the reviewers find that the review needs more work, they can change the state of a review to Needs Revision, which notifies the author.
5. Request further review: Authors can request a review of the revision and update any of the tasks they were asked to complete, thereby notifying the reviewers that they are ready for more feedback.
6. Approve or reject review: Reviewers can approve or reject a review using P4 Code Review. When they approve or reject a review, the review is considered closed.
7. Commit the review: For pre-commit reviews, authors can commit reviews using either:
   • P4 Code Review
   • their P4 Server clients, such as P4V or P4 for Visual Studio. In this case, committing a pre-commit code review is synonymous with submitting the changelist associated with the review.

Review State column of the Pending tab

If the review cannot be approved, the Pending tab has a Review State column shows a red icon next to "Needs Review". To learn which rules are "Blocking Approval", hover over "Needs Review" to see a tooltip:

If you attempt to submit, the Submit Changelist dialog box indicates why the P4 Code Review prevents submitting and allows you to open the review in P4 Code Review.

Set up the P4 Code Review integration

For details on how to set up the P4 Code Review integration, see Configuring P4 Code Review connections in the P4 Server Administration Documentation.

Example p4 property command to run:

p4 property -a -n P4.Swarm.URL -v https://swarm.yourcompanydomain.com

where https://swarm.yourcompanydomain.com is the URL for your P4 Code Review server.

If you are testing the P4 Code Review integration, you might want to set the property for a specific user. For example, to enable the P4 Code Review integration for the user username:

p4 property -a -u username -n P4.Swarm.URL -v https://swarm.yourcompanydomain.com

Similarly, you can enable the P4 Code Review integration for a specific group of users. For example, to enable the P4 Code Review integration for the group group:

p4 property -a -g group -n P4.Swarm.URL -v https://swarm.yourcompanydomain.com

Timeout

P4V uses a P4 Code Review integration timeout, in seconds, to limit delays in the P4V user interface. The timeout can be adjusted by running the following command:

p4 property -a -n P4.Swarm.Timeout -v 10

The default timeout value is 10 seconds. The timeout can be set for a specific user or a specific group by including the -u username or -g group options, respectively.

P4 Code Review integration features

When P4 Code Review integration is enabled, additional features are available in P4V, including new context menus, dialog boxes to request a review and update a review, badging on pending changes, committed changes, and history, as well as Review ID and Review State columns.

Request a review

You can request reviews from either pending or submitted changelists. Note that a changelist cannot be associated with more than one review. However, a review can have more than one changelist associated with it.

Best practices:

• Pre-commit code reviews are a more popular approach because they allow validating of code and correcting defects before they become a part of the committed code base. P4 Code Review supports pre-commit code reviews via pending changelists.
• Post-commit code reviews allow reviewers to provide feedback on the submitted content, and they allow the author to follow on with more submitted changes when making updates recommended by the reviewers. Development branches are well-suited for the post-commit review process.

Reviewers:

• When you select reviewers, you can make them required or optional.
• When you select a group as reviewer, you can make all members optional, all members required, or decide that only one member of the group is required to review.
• If a user is specified as an optional reviewer, but the same user is also the member of a group of which all members are required to review, then this user is actually a required reviewer.

Request a review from a pending changelist

To request a review from a pending changelist, do the following:

1. Go to the pending changelist tab, right-click the changelist, and select Request New P4 Code Review Review​.

   If the changelist is already part of a P4 Code Review review, this option is not available.

   

   The Request New P4 Code Review Review dialog box displays a list of files to be shelved in order to request the review. If the changelist already has shelved files, the dialog box also lists these already shelved files. The aggregate of the shelved files comprises the review.

2. In the Request New P4 Code Review Review dialog box, enter a description.

   Each review requires a description. The default description is the changelist's description.

3. Optionally, select additional options, including reviewers (users or groups), reverting checked out files after they are shelved, not shelving unchanged files, and opening the review in P4 Code Review.

   

4. Click Request Review.

   The pending changelist is badged with a P4 Code Review icon, and P4V updates the Review Id and Review State fields with their values from P4 Code Review.

   

Request a review from a submitted changelist

To request a review from a submitted changelist, to the following:

1. Go to the Submitted changelist tab, right-click the changelist, and select Request New P4 Code Review Review.

   If the changelist is already part of a P4 Code Review review, this option is not available.

   The Request New P4 Code Review Review dialog box displays the files to be added to the review.

2. In the Request New P4 Code Review Review dialog box, enter a description.

   Each review requires a description. The default description is the changelist's description.

3. Optionally, select additional options, including reviewers and opening the review in P4 Code Review.

4. Click Request Review.

   The pending changelist is badged with a P4 Code Review icon (), and P4V updates the Review Id and Review State fields with their values from P4 Code Review.

Update a review

If you need to update the files in a review for any reason, such as to respond to the feedback you received from the reviewers, P4V lets you update an existing P4 Code Review review.

Update a P4 Code Review review from a pending changelist

When updating a P4 Code Review review from a pending changelist, the changelist can—but does not have to be—already associated with the review.

Option 1: Update from an associated pending changelist

To update a review from a pending changelist that is associated with the review, do the following:

1. On the Pending tab, right-click the changelist and select Update P4 Code Review Review 'xxxx', where xxxx is the review ID.

   The Update Files in Review dialog box displays a list of files to be shelved in order to update the review. If the changelist already has shelved files, the dialog box also lists these already shelved files. The aggregate of the shelved files comprises the updated review.

2. If needed, update the review description.

3. Optionally, select additional options, including reverting checked out files after they are shelved, not shelving unchanged files, and opening the review in P4 Code Review.

4. Click Update Files.

   The files in the associated review are updated.

Option 2: Update from a pending changelist not associated with the review

To update a review from a pending changelist that is not yet associated with the review, do the following:

1. On the Pending tab, right-click the changelist and select Update P4 Code Review Review.

   This scenario is typical if you are working on a different machine than where you originally requested the review or if you have discarded the original changelist you used for creating the review. If you already have a changelist associated with the review, you would likely use that changelist and follow the instructions in option 1.

   The Update Files in Review dialog box displays a list of files to be shelved in order to update the review.

2. In the Update Review field, enter the ID of the review you would like to update with these files.

3. Optionally, to validate if this review is in fact the review you would like to update, click View Review Description.
4. Optionally, select additional options, including reverting checked out files after they are shelved, not shelving unchanged files, and opening the review in P4 Code Review.

5. Click Update Review.

   The changelist you used to update the review becomes associated with the review.

Update a P4 Code Review review from a submitted changelist

To associate a submitted changelist with an existing P4 Code Review review, do the following:

1. Right-click the submitted changelist and select Add to P4 Code Review Review.

   The Add to a P4 Code Review Review dialog box displays a list of files to be added to the review.

2. In the Update Review field, enter the ID of the review to which you would like to add these files.

3. Optionally, to validate if this review is in fact the review to which you would like to add these files, click View Review Description.
4. Optionally, select additional options.

5. Click Add to Review.

   The files are added to the review.

Open a review in P4 Code Review

If you leave the Open Review in P4 Code Review check box option selected in the Review Request or Review Update dialog boxes, P4V launches P4 Code Review to the review page in your default browser. This confirms that the review has been created or updated.

Get Files from a Review

You might be inspecting a review in P4 Code Review and decide you want a local copy of the files. The review ID shown in P4 Code Review corresponds to a pending changelist in P4 Server that contains these files. To get these files from P4V:

1. In P4V, open the Go To Spec dialog box with the keyboard shortcut of CTRL+F or COMMAND-G on Mac.

2. Enter the review ID and click OK.

   P4V displays the Pending Changelist dialog box.

3. Right-click the files you want to unshelve and select Unshelve.

   P4V displays the Unshelve dialog box.

4. Select the pending changelist to which you want these files to be unshelved and click Unshelve.

   P4V retrieves a local copy of these files into your workspace.

Review ID and Review State columns

P4V adds a Review Id and Review State column to the Submitted and Pending tabs and the History tab for connections that have the P4 Code Review integration enabled.

If you are connected to a P4 Server with the P4 Code Review integration enabled and do not see the columns, right-click the header row and select these fields.

Reconnect to P4 Code Review

If the connection to P4 Code Review is interrupted, you can re-establish it from the Connection > Reconnect to P4 Code Review menu.

This menu item is only available if the P4.Swarm.URL is defined.