Work with reviews in P4 Code Review

P4 Code Review is a powerful and flexible code review and collaboration solution that helps teams ship quality software faster. P4 Code Review enables review of code and other assets before or after commit and can be customised to fit into various workflows. P4 Code Review stores all of its metadata including reviews, projects and comments in P4 Server, which makes it an attractive solution since it doesn’t require backing up an external database. For more about using and installing P4 Code Review, please see the P4 Code Review Documentation.

Workflow of a review

Below is the happy path workflow for a P4 Code Review review. There are more permutations and variations that are described in the P4 Code Review documentation.

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 P4 Server.
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 meta-data including the author, reviewers and comments made on the review.
Provide review feedback: Reviewers can comment on files or on individual lines of files using P4 Code Review. Reviewers can also add follow-up tasks that the author would be asked to address before the review could be closed.
Request revisions: If the reviewers find the review needs more work, which is often the case, they can change the state of a review to Needs Revision, thereby notifying the author that the review is back in their court.
Request further review: Authors can request further review of their review content changes and update any of the tasks they were asked to complete, thereby notifying the reviewers that they are ready for more of their feedback.
Approve or reject review: Reviews can be approved or rejected using P4 Code Review. Once a review is approved or rejected, it is considered closed.
Commit the review. For pre-commit reviews, authors can commit reviews using their P4 Server clients such as P4V or P4 for Visual Studio. For this scenario, committing a pre-commit code review is synonymous with submitting the changelist associated with the review. They can also optionally use P4 Code Review to commit pre-commit reviews.

Set up the P4 Code Review integration

A minimum requirement for the P4 for Visual Studio integration is to run P4 Code Review version 2014.4.

None of the new features for P4 Code Review are available unless the P4 Code Review integration is turned on. This integration needs to be turned on for each P4 Server server. In order to make P4 for Visual Studio enable the P4 Code Review features, the P4 administrator must run the p4 property command for the P4 Code Review URL. This will tell the P4 Server server the P4 Code Review URL. The P4 for Visual Studio integration uses this URL when making API requests to the P4 Code Review server.

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 the P4 Code Review server.

If you are testing the P4 Code Review integration, you may wish 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_

Authentication with P4 Code Review

P4 for Visual Studio uses the user’s existing P4 Server ticket to communicate with P4 Code Review. If you get authorization errors, ensure that the Use IP-specific tickets when logging in is disabled. This is synonymous with using the -a option with the p4 login command so that the ticket can be used on any machine.

P4 Code Review integration features

Once the P4 Code Review integration is enabled a number of new features are available in P4 for Visual Studio including new context menus, review request and update dialogs, badging on pending and committed changes, as well as Review ID and Review State columns.

Request a review

Reviews can be requested 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.

Pre-commit code reviews are a more popular approach since 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 warrant that the author follow on with more submitted changes when wanting to make the updates recommended by the reviewers. Development branches are well-suited for the post-commit review process.

Request a review from a pending changelist

To request a review from a pending changelist, go to View > Pending changelists, select the changelist and choose the Request New P4 Code Review Review… from the context menu. Note that 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 displays a list of files to be shelved in order to request the review. If the changelist already has shelved files, the dialog also lists these already shelved files. The aggregate of the shelved files comprises the review. The review must have a description, which defaults to the changelists' description. The dialog offers additional options including: reviewers, reverting checked out files after they are shelved, not shelving unchanged files, and opening the review in P4 Code Review.

Once the review has been requested, the pending changelist is badged with a P4 Code Review icon and P4 for Visual Studio updates the Review ID and the Review State fields with their values from P4 Code Review.

It is a best practice for the author to keep this pending changelist for subsequent updates to the review. This same changelist can be used by the author to submit the review. If the review is rejected or the review is committed from P4 Code Review, then the author should manually discard this pending change so that it does not get accidentally committed.

Request a review from a submitted changelist

To request a review from a submitted changelist, go to the Submitted changelist tab, select the changelist and choose the Request New P4 Code Review Review… option from the context menu. Note that 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 displays the files that to be added to the review. The review must have a description, which defaults to the changelists' description. The dialog offers additional options including: reviewers and opening the review in P4 Code Review.

Update P4 Code Review 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, P4 for Visual Studio provides an option to update an existing P4 Code Review review.

Update a P4 Code Review review from a pending changelist

To update a review from a pending changelist that is associated with the review, go to View > Pending changelists, select the changelist and choose the Update P4 Code Review Review 'xxxx"… option from the context menu, where xxxx is the review id.

The Update Files in Review dialog displays a list of files to be shelved in order to update the review. If the changelist already has shelved files, the dialog also lists these already shelved files. The aggregate of the shelved files comprises the updated review. You can also update the review description at this time. The dialog offers additional options including: reverting checked out files after they are shelved, not shelving unchanged files, and opening the review in P4 Code Review.

Update a P4 Code Review review from a submitted changelist

To associate a submitted changelist with an existing P4 Code Review review, select the submitted changelist and choose Add to P4 Code Review Review context menu option.

The Add to a P4 Code Review Review dialog displays a list of files to be added to a review. The dialog has a field where you can enter the review id of the review to which you’d like to add these files. Type in the review id in the Update Review field and click the View Review Description button if you want to see a preview of the review’s description in order to verify that this is in fact the review you’d like to add these files to. The dialog offers an additional options to open the review in P4 Code Review.

Open review in P4 Code Review

If you leave the Open Review in P4 Code Review checkbox option selected in the Review Request or Review Update dialogs, then P4 for Visual Studio launches P4 Code Review to the review page in a new tab in [P4VS-2769] Microsoft Visual Studio (you can configure this to open in an external browser instead). This serves as confirmation that the review has been created or updated.

If a pending or submitted changelist is already associated with a review, context click the changelist and select Open Review 'xxxx' in P4 Code Review… to open the associated review, where xxxx is the id of the associated review.

If P4 Code Review is configured for authentication with P4 AS, you might need to log in again.

Review Id and Review State columns

P4 for Visual Studio will add a Review Id and Review State column to both the submitted and pending changelist tabs for connections that have the P4 Code Review integration enabled.

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