About reviews

PulseUno peer reviews enable you to collaborate and comment on the changes in you project. This topic describes the review workflow, the roles that users can hold on a review, and the rules that trigger review transitions.

Overview

Use peer reviews to:

  • Review and comment on the changes in your development projects.
  • Collaborate with team members.
  • Get insight into the health of changes in your changesets, streams, and branches, such as the results of chain runs.
  • Promote team work and development best practices.
  • Vote to approve reviews or ask for changes, which may cause reviews to be marked as approved or sent for rework.

Administrators and review owners (authors) can also perform these tasks:

Review owner Abandon a review.
Administrator
  • Change a review's owner.
  • Send a review for rework back to its owner.
  • Change a review's state.
  • Abandon a review.

To view all the reviews that have been created for the selected user, space, product, or stream, see Use review lists.

To view information about a specific change, see View information on review pages.

Reviews are also displayed on the activity feed for a space, product, Git repository, stream/branch, and My Work.

You can use the configurable review rules to control how a review's state is changed. For details, see Review rules.

Back to top

Review states

The following diagram displays PulseUno's review states and state changes.

Review states and state changes

Reviewers vote to approve, send for rework, 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.

Considerations and behaviors:

  • If a review's state is changed by mistake to Approved, an administrator can move the review to Rework.
  • If a problem is found while reviewing, a reviewer can request changes (which may change the review's state to Rework).
  • If a request's state changes from its peer review state to a previous state, the associated reviews automatically move back to Rework.
  • When a request is closed, an associated review at the Approved state automatically moves to Completed.
  • Administrators can change a review's state at any time.

Review states:

Draft The review is being modified by the owner (author).
In Review The review has been published. Reviewers can add comments and vote on the review.
Rework The review has been sent back to its owner with suggestions for improvement.
Approved The review's changes have been accepted.
Completed If there are no issues, the Approved review is normally marked as Completed by the owner.
Abandoned Administrators or review owners can change a review to Abandoned at any time. The review is closed and removed from circulation.

Back to top

Review roles

You can hold one of the following roles on a review:

Role Description
Owner Normally the user who delivered the changeset that created the review. Administrators can change the owner to any valid user.
Lead reviewer

Can be assigned automatically from the changeset and modified manually.

Dimensions CM: The valid lead reviewers are derived from the real role assignments on the design parts in Dimensions CM that own the items being reviewed.

Git: Any active user is a valid lead reviewer.

A lead reviewer can add optional reviewers.

Optional reviewer

Normally assigned manually.

Dimensions CM: The valid optional reviewers are derived from the candidate role assignments on the design parts in Dimensions CM that own the items being reviewed.

Git: Any active user is a valid optional reviewer.

Optional reviewers cannot assign other reviewers.

Delivery filters control which changesets automatically create reviews.

Dimensions CM: 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.

Git: All active users are available to be assigned as lead or optional reviewers.

Back to top

Review rules

The following actions trigger a change in a review's state:

  • A user with the appropriate role (Owner 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, request changes, or abstain with no opinion on a review that is at the In Review state.
  • The owner of a review is changed.
  • The reviewers assigned to a review are changed manually.
  • Dimensions CM: A request associated with a review is actioned to the In Review state in Dimensions CM. 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. See Review rule scripts.

Back to top

Review rule scripts

A rule script is a JavaScript file that has access to specific properties of the review for which it is invoked.

The PulseUno installer saves a set of built-in review rule scripts to the following directory:

<PulseUno data directory>/conf/rules/examples/

You can create your own scripts or modify the available scripts. See Custom rule scripts.

This table describes the review rule scripts bundled with PulseUno.

Script Description
defaultRule.js

This script approves or rejects reviews based on the vote of the first reviewer. This is the default rule script for reviews.

The script automatically changes the review state from:

  • Draft or Rework to In Review when a request is actioned to the Peer Review state.
  • In Review to Approved or Rework after the first vote has been cast by any reviewer.
allMustApprove.js This script handles reviews based on the approval of all reviewers. If any of the reviewers don't approve, the review state changes to Rework.
defaultPRRule.js

This script approves or rejects pull requests based on the vote of the first reviewer. This is the default review rule script for pull requests.

The script automatically changes the review state from:

  • Draft or Rework to In Review when a request is actioned to the Peer Review state.
  • In Review to Approved or Rework after the first vote has been cast by any reviewer.
  • In Review or Approved to Rework if a new changeset is committed to the pull request’s source stream.
leadsOnly.js This script approves or rejects reviews based on the vote of the first lead reviewer.
majorityDecides.js This script handles reviews based on the approval of a majority, excluding reviewers with no opinion. If half or more reviewers don't approve, or if all reviewers abstain with no opinion, the review state changes to Rework.

For details on how to set the rule script for a product/Git repository or stream/branch, see Configure how reviews are created.

Back to top

Custom rule scripts

You can modify available review rule scripts or create your own scripts.

Note: A rule script can make changes only to a review’s state.

You create a rule script in a text file with the filename extension .js and save it to the following directory:

<PulseUno data directory>/conf/rules/

For details on how to set the rule script for a product/Git repository or stream/branch, see Configure how reviews are created.

Back to top

See also: