Review code

This topic provides details on how to review code.

About reviews

Overview

You can use peer review to:

  • Comment on, and review, the changes in your development projects.
  • Collaborate with team members.
  • Get insight into the health of changes in your changesets and streams.
  • Promote team work and development best practices.
  • Vote to approve or reject reviews, which may cause reviews to be marked as approved or sent for rework.

If you are a user with administrator rights you can also:

  • Change a review's author.
  • Send a review for rework back to its author.
  • Change a review's state.
  • Abandon a review.

The review list displays all the reviews that have been created for the selected user, space, product or stream. A review page displays information about a specific change. You can control how a review's state is changed with the configurable review rules.

Reviews are also displayed on the activity feed for spaces, products, streams, and on the user's Home page.

Create reviews

If you are an administrator you can configure changesets to automatically create reviews.

Review States

PulseUno's review states and state changes are:

Reviewers vote to approve, reject, and abstain from a review. Depending on the configurable rules their votes may cause a state change, or contribute to a state change in the future. By default, the first reviewer to vote on a review changes its state but different rules may be configured in your environment.

The following table describes the different review states:

Review state Description
Draft The review is being modified by the user who is the author.
In Review The review has been published. Reviewers can add comments and vote on the review.
Approved The review's changes have been accepted.
Rework The review has been sent back to its author with suggestions for improvement.
Completed If there are no issues the Approved review is normally marked as Completed by the author.
Abandoned A review can be changed to Abandoned at any time by an administrator. The review is closed and removed from circulation.

Review Roles

A user can hold one of the following roles on a review:

  • Author. Normally the user that delivered the changeset that created the review. The author can be changed by an administrator to any valid user.
  • Lead reviewer. Can be assigned automatically from the changeset and modified manually. The valid lead reviewers are derived from the real role assignments on the design parts in the SCM that own the items being reviewed. A lead reviewer can add optional reviewers.
  • Optional reviewer. Normally assigned manually. The valid optional reviewers are derived from the candidate role assignments on the design parts in the SCM that own the items being reviewed. Optional reviewers cannot assign other reviewers.

Delivery filters control which changesets automatically create reviews. The SCM's role assignments on the items in the changeset determine which users are automatically assigned as lead reviewers or are available to be assigned as optional reviewers.

Review Rules

A change in a review's state is triggered by one of the following:

  • A user with the appropriate role (Author or Administrator) changes the review state manually.
  • A decision made by a review rule that has run automatically. The review rules are codified as a script that runs when one of the following significant events occur:
  • A new changeset is associated with a review, which may automatically assign reviewers to the review.
  • A user manually changes the state of a review.
  • A reviewer votes to approve, reject, or abstain with no opinion on a review that is at the In Review state.
  • The author of a review is changed.
  • The reviewers assigned to a review are changed manually.
  • A request associated with a review is actioned to the In Review state in the SCM. This may automatically assign reviewers.

A rule script uses the votes of the lead and optional reviewers, and additional information, to decide whether to change a review's state. You can create, or modify, scripts and set the default rule script for each stream.

If you are using the built-in defaultRule.js rule script the default behavior automatically changes the review state from:

  • Draft to In Review when a reviewer is assigned.
  • In Review to Approved or Rework after the first vote has been cast by any reviewer.

Back to top

Review list

A review list displays the following:

  • Spaces. Reviews for all products and streams
  • Products. Reviews for all streams
  • Streams. Reviews for the current stream

To open a review list:

  1. Select a space, product, or stream.
  2. On the sidebar select Reviews.

Each row in a review list is a separate review and includes the following information:

  • An icon that indicates the review's current state, for example, In Review or Approved
  • The review's label (number and title)
  • The date the review was created
  • The stream associated with the review
  • The user who created the review
  • The users who are reviewing the review

You can select a filter to modify the type of reviews that are displayed.

  1. Open a review list.

  2. From the Reviews list select a filter.

    Note: Only users with administrator privileges can filter reviews that are at the Completed or Abandoned state.

You can also sort the reviews by category, and in ascending or descending order.

  1. Open a review list.
  2. Click Sort by.
  3. Select a category.
  4. Optionally select, or unselect, Sort descending.

Back to top

Review pages

Each review page displays the following information:

  • An icon that indicates the review's current state, for example, In Review or Approved.
  • The review's ID and title.
  • The associated stream.
  • Reviewer votes.
  • Description of the review and comments on the entire review.
  • The review author and the lead and optional reviewers.
  • Recent activity on the review.
  • Related requests.
  • The changesets associated with the review.
  • The files and folders associated with the changesets.

  • The contents of the files in the review.

    Tip: You can use keyboard shortcuts to navigate around a review page.

Description

The following are displayed in the Description section on the Conversation tab.

  • The description of the review.
  • Any comments made that apply to the entire review.

Activity

The recent activity on the review is displayed in the Activity section, for example:

The delivery that created the review.

You can filter the information that is displayed:

  • Discussions & Deliveries: only displays user generated events (such as Review sent for rework) and comments added by reviewers.

Requests

Related requests are displayed in the Requests section and a summary of the first one is expanded. Click the title of any review to view its details.

If the same request is used by multiple reviews, you will see links to those other reviews under the request’s title.

Changesets

The changesets associated with the review are displayed in the Changesets section. Multiple changesets are associated with a review if users have made several deliveries to a stream using the same request.

If a review is associated with multiple changesets you can filter the files that are displayed.

  1. In the Changesets section select two changesets to compare with each other.
  2. Click View Selection. The contents section and the sidebar are updated and only files that have changed between the selected changesets are now displayed.

Contents

The Contents section, and the sidebar, display all the files and folders in a review. You can view the contents of any file and add comments.

Back to top

Publish a review

When a review is created its initial state is Draft. If you are the review author, or a user with administration privileges, you can publish the review so that it is available to your team. The author is normally the user that delivered the changeset that created the review.

  1. On the review list page select the review you want to publish.
  2. Click Publish.
  3. Click Publish Review. The review is now at the In Review state.
    Note:
  • Once a review has been published, new changesets delivered using its request will create a new review instead of being appended to the published review.
  • You can move a published review back to the Rework state to make it eligible to receive further changesets you intend to deliver using the request.

Back to top

Add and remove reviewers

Each review can have reviewers with these roles:

  • A review author; normally the user who delivered the changeset that created the review.
  • One or more lead and/or optional reviewers.
    Note:
  • A review author, or an administrator, can add and remove lead and optional reviewers.
  • A lead reviewer can add and remove optional reviewers.
  • Adding reviewers to a Draft review may cause the review to change state to In Review. This can prevent the author from adding more reviewers. So select all the reviewers you want to add at once, or select a different review rule script in stream settings.

To add reviewers to a review:

  1. Open a review.
  2. In the Reviewers section, click Add and then Lead Reviewer or Optional Reviewer.

  3. Select one or more reviewers.

      Tip:
    • Control click to select multiple users.
    • Use Search to find users.
  4. Click Add Reviewers.

To remove reviewers from a review:

  1. Open a review.
  2. In the Reviewers section select one or more reviewers.
  3. Click Remove and confirm.

Back to top

Browse the contents of files in a review

The Contents section, and the sidebar, display all the files and folders in a review. Changes to files and folders, and to lines and characters in files, are displayed with these colors:

Color Description
File added
Line and/or characters added
File deleted
Line and/or characters deleted
Line and/or characters deleted
File renamed

The sidebar displays the total number of files in the review.

The Contents section displays the number of files and folders that have been added, modified, renamed, and deleted.

Click a file to view its contents. Use the Show menu to control how the file contents are displayed.

    Tip:
  • Binary files are not displayed but you can download them.
  • If a file is marked as binary but you know it is a text file, from the Show menu select As Text.
  • If only part of a file's contents are displayed, from the Show menu select Entire File.
  • Only the contents of the first 30 files are displayed. To display more files scroll to the bottom of the review page and click Load more.
  • To display the previous revision of a file, from the Show menu select Previous.
  • To combine the previous and current revisions of a file, from the Show menu select Unified.
  • To display the previous and current revisions of a file in separate columns, from the Show menu select Display Side by Side. The current version is displayed on the right tab and the previous version on the left tab.
  • Lines that have been added, or have new characters, start with a '+' (plus) character.
  • Lines that have been deleted, or where characters have been deleted, start with a '-' (minus) character.
  • To control how white space is displayed, from the Show menu select a white space option.

Back to top

Add comments to files in reviews

You can add comments to files in a review and collaborate with team members. Each reviewer receives an email with a snippet of the code and the review comments. This is different to adding a comment to an entire review.

  1. On a review page find a file.

  2. In the line number column, click and drag to select the lines where you want to add a comment.

  3. In the Comment box enter your comments. Optionally, format the comment using the toolbar or markdown syntax.

    Tip: You can also email comments to users who are not included in a review, for example, you want the opinions of other developers.

    1. On the toolbar, click Mention or enter the @ character in the comment box.
    2. Start typing the name of a registered user, PulseUno automatically displays the names of users that match.
    3. Select a user.

    4. Repeat to add additional users.

  4. To display how your comment will look, click Preview. To continue editing click Edit.
  5. To add the comment click Comment. Your comments are now visible to your team and their responses will be displayed in the same comment box.
    Note:
  • Comments are tied to the file version where they were added and shown when that version is displayed.
  • Comments are not added to the actual file versions.
  • You can add comments to reviews at specific states.
  • You can edit your own comments until there is a reply.

Back to top

Vote on a review

You can vote to approve or reject a review. Depending on how the rules script for this stream is configured, your vote may trigger the rule script to move the review to its next state.

  1. At the top of a review click Approve or Reject.
  2. Enter the reasons why you are voting to approve or reject the review.
  3. Optionally format your comment (see the markdown reference).
  4. To display how your comment will look click Preview. To continue editing click Edit.
  5. If a check list is presented, select items that have influenced your voting decision.
  6. Click Approve or Reject.

Note: Administrators can create review check lists and set the default for each product.

You can also abstain from voting. This useful if there is a rule that mandates that all reviewers must vote, but you have no opinion.

  1. Open a review.
  2. Click More and select Abstain with No Opinion.
  3. Enter a reason for abstaining and click Abstain.

Back to top

Mark a review as Approved

If you are a user with administrator privileges you can bypass reviewer voting and mark a review as Approved.

  1. Open a review.
  2. Click More and select Mark as Approved.
  3. Click Approve Review.

Back to top

Change a review’s author

If you are a user with administrator privileges you can change a review's author.

  1. Open a review.
  2. Click Change Author.
  3. Select a user.
  4. Click Change Author.

Back to top

Send a review for rework

If you are a review author, or a user with administrator privileges, you can send a review back to its author for rework with suggestions for improvement, and bypass reviewer voting.

  1. Open a review.
  2. Click More and select Send for Rework.
  3. Click Send for Rework.

Back to top

Abandon a review

If you are a review author, or a user with administrator privileges, you can abandon a review. Abandoning a review indicates that it is no longer active and stops further review activity. This action cannot be reversed.

  1. Click More and select Abandon Review.
  2. Click Abandon Review.

Back to top

Close a review

If you are a review author, or a user with administrator privileges, you can close a review. Closing a review prevents further changes being made to it. Only close a review if you are sure that no further work is required.

  1. Open a review.
  2. Click Close Review and confirm.

Back to top

Add comment to an entire review

You can add comments to an entire review when it is at specific states. Comments appear in a review's activity feed. This is different to adding comments to a specific file in a review.

  1. Open a review.
  2. Select the Conversation tab and click Join in the conversation under the review Description.
  3. Optionally format your comment. To display how your comment will look click Preview. To continue editing click Edit.
  4. When you have finished click Comment.

Back to top

Edit a review's title

You can edit a review's title.

  1. Open a review.
  2. Click More and select Edit Title.
  3. Enter a new title and click Save.

Back to top

Customize Review page defaults

You can set display defaults for the files in your reviews:

  • Display comments made by reviewers
  • Display the entire contents of each file
  • Display the previous version of each file
  • Unify the previous and current differences of each file

You can also select a white space options, for example, Ignore White Space.

Note: Customizations are only applied to your review pages and do not affect other users.

  1. Click More and select Display Defaults.
  2. Select Options.
  3. Click OK.

Back to top

Manage review check lists (Administrators)

When a user votes to approve or reject a review they are typically required to select items from a check list. Administrators can create different types of check lists to satisfy different levels of severity. For example:

  • Secure. A complex check list with high levels of tightly controlled compliance, for example, for licensing.
  • Minimum. A small list with low levels of compliance, for example, for in-house testing.

For each stream the same check list is used for approvals and rejections, however, you can associate a different review check list with each stream.

To create a review check list:

  1. On the top navigation click Administration.
  2. Select Check Lists.
  3. Click New Check List.
  4. Enter a name for the check list.

  5. Enter items that you want your reviewers to select when voting to approve or reject reviews. Review check lists may contain up to ten items. For example:

    • Coding standards
    • Export compliance regulations
    • Software complexity rules
  6. Click Save.

To delete review check lists:

  1. Select Administration | Check Lists.
  2. Select one or more check lists.
  3. Select Delete and confirm.

You can also select the default check list for a product.

Back to top

Watch a review

You can optionally watch a review when it is at specific states. When changes are made to the review you will be notified by email. You can select the notifications that you receive.

  • To watch a review click Watch.
  • To stop watching a review click Unwatch.

Back to top

Automatically create reviews

Administrators can configure changesets to automatically create reviews. The first delivery of a changeset to your SCM tool creates a new PulseUno review whose title is the same as the delivery change comment. If the review is related to a specific request, subsequent deliveries that use the same request are grouped under the same review.

Create delivery filters (Administrators)

Delivery filters enable administrators to control how reviews are created, for each stream. Every path in a changeset is matched against the patterns in a stream's delivery filter. If one or more paths pass through the filters, the changeset delivery creates reviews. The default delivery filter for a product is used by any streams in that product that do not have an assigned delivery filter.

  1. Select the product where you want to create a delivery filter.
  2. On the sidebar select Delivery Filters under Settings.
  3. Select New Delivery Filter.
  4. In the Title box enter a name for the new delivery filter.
  5. In the Note box optionally enter information about the filter.

  6. Use the Changeset Path Filtering section to control which paths create reviews. In the Include these paths box do one of the following:

    • To only create reviews for specific paths, enter Ant style patterns (one pattern per line), for example:

      **/*.java

      **/*.jsp

    • To create reviews for all changesets, leave blank. In the Exclude these paths box do one of the following:

      • To prevent specific paths from creating reviews, enter Ant style patterns (one pattern per line), for example:

        **/.DS_Store

        **/tmp/**

      • To create reviews for the included changesets, leave blank.
  7. If you have a system that delivers changes using specific user names, for example a build process, you can ignore those changesets. In the Exclude changesets delivered by these users box enter the user names (login IDs) on separate lines. For example, regbuild excludes all deliveries by the user with the login ID regbuild. Leave this box blank to disable it.
  8. To ignore changesets with specific text in their delivery comments, in the Exclude changesets with these messages box enter message patterns, where * is a wildcard character and each pattern is on a separate line. For example, *NO_REVIEW* excludes deliveries where the message contains the keyword NO_REVIEW. Leave this box blank to disable it.
  9. Click Save.
  10. To make this the default delivery filter for this product, on the Delivery Filters page select the filter. Click Set As Default and then Make Delivery Filter Default. A product can have one default delivery filter.

Automatically Create Reviews (Administrators)

Administrators can configure which changesets delivered to streams automatically create reviews.

  1. Select the stream that you want to configure.

  2. On the sidebar select Stream Settings.

  3. To control which changesets delivered to this stream create reviews, apply a delivery filter:

    1. Select Override default delivery filter. If you want all changesets that are delivered to this stream to create a new review, do not select this option.
    2. From the Delivery Filter list select the Filter deliveries using.

  4. To specify a review check list to be used with new reviews created in this stream, from the Review Check List To Use list select one of the following:

    • The product's default check list
    • Any other list that has been defined
    • No review check list

  5. To specify the review rules for this stream, from the Review Rules To Use list select the product's default rule or any other rule that has been defined.

  6. To configure if changesets that pass through the selected delivery filter create or attach deliveries to new reviews, from the Create/Attach Deliveries to a Review list select one of the following:

    • The product's default setting
    • Create or attached deliveries to reviews
    • Do not attach deliveries to reviews

    Note: If an existing review is associated with an SCM request, a new changeset is attached to that review (instead of creating a new one) when the following conditions are met:

    • The review is at the Draft or Rework state.
    • The changeset uses the same request, or has the same review label, in its changeset delivery message.
    • The changeset is associated with the same stream.

  7. Click Save.

Back to top