Helix Core is now P4 and Helix Swarm is now P4 Code Review. Product user interfaces will be updated soon. Learn more >>

Documentation | 2025.3

# States

Reviews can be in one of several states. The biggest differentiator is whether the review's files have any outstanding, uncommitted changes or not.

Whenever a review state changes, an email notification is sent to all review participants, including:

- The review author
- Any user who comments on the review or its files
- Any user who has changed the review's state previously
- Any user who is @mentioned, or a member of a group that is @@mentioned in the review's description or comments.

The review state is indicated by the Review state icon on the Review page. The Change state button is used to change the state of a review, see Change review state.

Code reviews can be in one of the following states:

- Needs review: The review has started and the changes need to be reviewed.
- Needs revisions: The changes have been reviewed and the reviewer has indicated that further revisions are required.
- Approved: The review has completed. The changes may need to be committed. If the changes have been committed then this review will be Approved and closed, otherwise it will be Approved and open. See the note below.
- Rejected: The review has completed. The changes are undesirable and should not be committed.
- Archived: The review has completed for now. However, it is neither rejected nor approved; it is simply put aside in case it is needed in the future.

By default, when an Approved review is committed or updated, P4 Code Review changes the state to Needs Review if the files have been modified since the review was approved. Files are considered modified if the list of involved files changes, or if the file content or file-type changes.

If one or more files in a review has the filetype +k (`ktext`), this behavior is undesirable because the files will appear to be modified when the P4 Server replaces RCS keywords with their current values. See Unapprove modified reviews to see how to disable this behavior.

## Self-approval by review authors

By default, review authors can approve their own reviews. This behavior is based on P4 Code Review's advisory nature.

Self-approval by authors can be prohibited on a project-by-project basis by specifying moderators for project branches (see State change restrictions with moderation). However, authors who are moderators can self-approve their own reviews.

Administrators can configure P4 Code Review to prevent all self-approval by review authors. See Disable self-approval of reviews by authors.

## State change restrictions with moderation

Typically, any authenticated user can change the state of a review (remember that the review state is merely advisory in most cases).

When you add a moderator to a project branch, only the moderators can approve or reject reviews restriction is enabled for a project branch. See Project settings for details on adding moderators to project branches.

Changing the state of any review associated with a moderated branch is restricted as follows:

Only moderators can approve or reject reviews on the branch.

To add moderators to a branch:

1. Click the Manage moderators button.

2. Choose the Users or Groups tab.

   1. If you selected Users, start typing a the name of a user. Suggested users on the P4 Server will appear automatically.

   2. If you selected groups, then all of the members of that group will have the same moderator privileges for that project branch. Use this option if you wanted to add several users at once.

3. Click Add.

After you finish setting up the branch and save the project, reviews on this branch can only be approved or rejected by moderators.

Moderators can also transition a review to any other state. Below is a summary of branch moderator roles and review state rules.

Role | Allowed actions | Restrictions
--- | --- | ---
Moderators | Can move a review to any state. Can approve or reject reviews. Can prevent automatic approvals. | None (unless `disable_self_approve` is enabled for self-approval). For more information, see `disable_self_approve`.
Authors (not moderators) | Can change state to: Needs review Needs revision Archived Can attach committed changelists. | Cannot approve or reject reviews.
Authors (also moderators) | Can change state to: Approve Rejected Needs review Needs revision Archived Can attach committed changelists. | Cannot approve their own reviews if `disable_self_approve` is enabled. For more information, see `disable_self_approve`.
Project members | Can change state to: Needs review Needs revision Can attach committed changelists. | Cannot approve, reject, or archive reviews.
Other users | None | Cannot change review states.
All roles | Can start a review. | Cannot change state if it’s not in their allowed states (for example, can’t change from Rejected).

Additional notes

- Moderators can prevent automatic approvals. For more information about automatically approving reviews using workflow rules see Workflow rules.

- By default, if a review spans multiple branches with different moderators, only one moderator from any branch needs to approve it. You can change this (via a global setting) to require one moderator per branch. If a moderator belongs to multiple branches, one approval counts for each. For instructions on how to configure moderator behavior, see Moderator behavior when a review spans multiple branches.

To delete a moderator, click the delete icon against their name.

## State change restrictions without moderation

Changing the state of any review associated with a project that has no moderation is restricted as follows:

- Only members and the review author can change the state of a review or attach commits.

- If a user or group is added in Members or groups who can ignore ALL workflow rules list in the Global Workflow setting, they can transition the review state.

## Required reviewers

Reviews can optionally have required reviewers. When a review has required reviewers, the review cannot be approved until all required reviewers and required reviewer groups have up-voted the review. If the review is associated with a project that has assigned moderators, even the moderators cannot approve the review without up-votes from all required reviewers (but they can reject the review).

When a group is a required reviewer, it can be set to operate in one of two ways:

- Require all: all members of the group must up-vote the review to allow the review to be approved.
- Require one: at least one member of the group must up-vote the review to allow the review to be approved. If any member of the group down-votes the review, the review cannot be approved.

Required reviewers are expected to take greater care while performing a review than non-required reviewers, as their votes affect whether a review can be approved or not.

To edit the reviewers for a review and to change whether a reviewer is required or not, see Edit reviewers.

If a review involves a branch with assigned moderators, only a moderator can approve the review, even if all required reviewers have up-voted the review.

See Project settings for details on adding moderators to project branches.

## Change review state

The Change state button on the Review display page is used to manually change the state of a review.

To change the state of the review:

1. Navigate to the review you want to update.
2. Click the Change State button.
3. Select the new state from the dropdown menu.
   The options available depend on the current state of the review and your user permissions:

- Needs revision: Select to request changes to the files in the review.
- Needs review: Select to request further review of the changes.
- Approve (only available if the voting requirements for the review are satisfied. For information on voting requirements, see Required reviewers): select to approve the review.
- Commit (only available for pre-commit reviews that have been approved): Select to commit the review.
- Approve and commit (only available for unapproved pre-commit reviews when the voting requirements for the review are satisfied. For information on voting requirements, see Required reviewers.): Select to approve and commit the review in a single step. See Approve and commit.
- Reject: Select to reject the review.
- Archive: Select to archive the review.

### Approve and commit

Approve and commit is available in the dropdown menu for unapproved pre-commit reviews, this enables you to approve and commit a review in a single step if required.

- By default, any authorized user can commit a review. P4 Code Review can be configured to restrict this behavior so that only the review author can commit the review, see Disable commit for details.
- Approve and commit is only available for unapproved pre-commit reviews when the voting requirements for the review are satisfied. For information on voting requirements, see Required reviewers.

If P4 Code Review is configured to prevent approval of reviews with open tasks and a review has open tasks, the Approve, and Approve and commit options will not be available for the review. This option is configured by an administrator. See Disable approve for reviews with open tasks.

To approve, or approve and commit a review with open tasks, you must address the tasks first and then set them to Task Addressed, or Not a Task. See Set a task to Task addressed or Not a task for details.

1. Select Approve and commit from the dropdown menu.
2. The Commit Review dialog is displayed.

3. Edit the review description if required.
4. Select which jobs should be associated with the review, and specify the job status on commit.
5. Select Remove pending changelists, P4 Code Review will attempt to automatically clean up any changelists left behind after the review has been committed, including removing any shelved files. This option can be removed by an administrator, see Review cleanup for details.
6. Click Approve and commit to approve the review and commit the associated files.

By default, P4 Code Review records that you committed the review on behalf of the review's author. This can be configured by an administrator to only credit the committer and not the review author, see Commit credit for details.

Your search for returned results