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.

The peer reviews process enables you to:

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 Work with review list.

To view information about a specific change, see View details in reviews.

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

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

Review states

Reviewers vote to approve, send for rework, and abstain from a review. Depending on the configurable rules, the 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 the review state, but different rules may be configured in your environment.

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

Review states and state changes

The following table describes each review state.

State	Description
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.

Considerations and behaviors:

If a review's state is changed to Approved by mistake, an administrator can move the review to Rework.
If a problem is found while reviewing, a reviewer can request changes. This 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 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.

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.

Review rules

A review can transition to another state when an administrator or owner changes the review state manually or when a review rule is applied. A review rule triggers the change automatically, based on a set of conditions defined for the rule.

The review rules are codified as a script. For details, see Rule scripts.

The review rule script 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 review owner 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.

Rule scripts

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

By default, 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. For details, 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.

Custom rule scripts

You can modify built-in review rule scripts or write your own scripts.

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

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/

You can apply custom rule scripts to Git repositories. If you want to apply the rule to a specific Git repository, you can save the rule in the repository, in the directory .pulseuno/rules.

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