Reviewers and approvals

Reviews involve multiple participants who contribute to the review process and determine whether a review can be approved. By default, review participation is advisory, but projects can be configured to require approval from specific reviewers, reviewer groups, moderators, workflows, or checklists before a review can be approved.

Review roles permissions

The following table summarizes the permissions available when moderation is enabled for a project branch.

Role	Approve Review	Reject Review	Change review state	Additional Notes
Moderator	Yes	Yes	Any State	Can prevent automatic approvals.
Authors (not moderator)	No	No	Needs Review Needs Revision Archived	Can add committed changelists.
Authors (also a moderator)	Yes*	Yes*	Any State	*Subject to self-approval restrictions. In the config, if disable_self_approve is enabled, you cannot self approve. To learn more, see disable_self_approve.
Project member	No	No	Needs Review Needs Revision	Can add committed changelists.
Other user	No	No	None	Cannot change review state.
All roles	N/A	N/A	Can start a review.	State transitions depend on permissions and review rules.

Moderators

A moderator is a user assigned to moderate reviews for a specific project branch. Project administrators can assign users or groups as moderators for project branches.

When moderators are configured for a branch, only moderators can approve or reject reviews associated with that branch.

To learn more about configuring moderators, see Configure a project for details on adding moderators to project branches.

Moderator responsibilities

Moderators can:

• Approve reviews.

• Reject reviews.

• Change review state.

• Prevent automatic review approvals.

• Participate in reviews like any other reviewer.

When a review is associated with a moderated branch, review state changes can be restricted. For example, non-moderators cannot approve or reject reviews for that branch.

Multi-branch moderation

Some reviews span multiple project branches.

By default, when a review includes multiple moderated branches, approval from one moderator is sufficient. Administrators can configure P4 Code Review to require approval from a moderator for each moderated branch.

If a moderator belongs to multiple moderated branches included in the review, a single approval can satisfy the moderation requirement for each of those branches.

Moderator approval rules

Moderators must still satisfy all approval requirements before a review can be approved.

For example, moderators cannot approve a review if:

• Required reviewers have not approved the review.

• Approval requirements defined by project configuration have not been satisfied.

• Workflow rules prevent approval.

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

• To learn more about required reviewers, see Required reviewers.

• To learn more about workflow requirements, see Workflow merging.

Authors

The review author is the user who creates the review from a changelist.

Author responsibilities

Review authors are responsible for:

• Creating and updating reviews.

• Responding to review feedback.

• Updating review content when changes are required.

• Managing review participants.

• Driving reviews to completion.

Author permissions

Authors can perform a range of actions throughout the review lifecycle.

Manage reviewers

Authors can add reviewers when creating a review or updating an existing review.

The following reviewer syntax can be used in changelist descriptions:

• @userid adds an optional reviewer.

• @*userid adds a required reviewer.

• @@groupid adds an optional reviewer group.

• @@*groupid adds a required reviewer group where all group members must approve.

• @@!groupid adds a required reviewer group where one group member approval is sufficient

To learn more about reviewer syntax, see Links in descriptions and comments.

Authors can also use the Edit Reviewers option to add, remove, and modify reviewers on an existing review.

To learn more about the Reviewers section of the review page, see Information panel.

Create and update reviews

Authors can:

• Start reviews from:

  • P4 Code Review

  • P4

  • P4V

• Update review content.

• Update review descriptions.

• Add changelists to reviews.

• Use work-in-progress tags (#wip by default) to pause review updates while changes are still being developed.

To learn more, see Start and update reviews, Add changelists, and Work with shelves and review files.

Commit reviews

Authors can commit approved reviews by selecting Commit from the review state options. Depending on project configuration, additional approval requirements might apply before a review can be committed.

To learn more, see Approval rules.

Manage review files

Authors can:

• Add changelists to reviews.

• Delete shelves that are no longer required.

• Work with review files and shelves throughout the review lifecycle.

To learn more, see Add changelists and Work with shelves and review files.

Manage checklist items

Authors might be able to update checklist item status depending on checklist configuration.

To learn more, see:

• Checklists

• Manual review

• AI review

Reviewers

A new review does not have any reviewers assigned unless default reviewers are configured for the project or branch.

Reviews that do not have any reviewers are considered inactive. Once reviewers join, vote, or comment, the review becomes active and is listed as having reviewers.

To learn more about review participation through comments, see Comments.

Default reviewers

Projects and project branches can have default reviewers configured. When a review is created, the configured default reviewers are automatically added to the review.

To learn how default reviewers can be added automatically when review content changes, see Branch inheritance.

Join a review

Users can become reviewers by:

• Selecting Review actions > Join review.

• Voting on a review.

• Commenting on a review or review file.

Once a user participates in a review, they are added to the review's reviewer list.

Leave a review

To leave a review:

1. Open the review.

2. Select Review actions > Leave review.

Your name is removed from the reviewer list and you no longer participate in the review.

You cannot leave a review if:

• You are a retained default reviewer.

• You are participating through a reviewer group.

Optional reviewers

Optional reviewers can comment and vote on reviews, but their approval is not required before a review can be approved.

Required reviewers

Reviews can have required reviewers. A review cannot be approved until all required reviewer requirements have been satisfied. If the review is associated with a moderated branch, moderators still require the necessary required reviewer approvals before the review can be approved. However, moderators can still reject the review.

Required reviewers are expected to take greater care when reviewing changes because their votes directly affect whether a review can be approved.

Authors can add required reviewers when creating a review or update reviewer requirements later by using the Edit Reviewers option on the review page.

To learn more about reviewer keywords used during review creation, see Add reviewers during review creation.

Individual reviewers

Add a required individual reviewer using: @*userid

The review cannot be approved until that reviewer has approved the review.

Require One groups

Add a Require One reviewer group using: @@!groupid

At least one member of the group must approve the review before it can be approved.

If any member of the group votes down the review, the review cannot be approved.

Require All groups

Add a Require All reviewer group using: @@*groupid

All members of the group must approve the review before it can be approved.

Required reviewers and moderators

Required reviewer requirements and moderation requirements work together.

If a review is associated with a moderated branch:

• Required reviewers must still approve the review.

• Moderator approval is still required.

• A moderator cannot approve a review until the required reviewer requirements have been satisfied.

To learn more, see Moderators and Approval rules.

Voting

Reviewers can vote on reviews to indicate approval or disapproval of the proposed changes.

To learn more about review versions and version history, see:

• Review versions

• Votes and review versions

Upvotes

An upvote indicates support for the reviewed changes and can contribute toward approval requirements.

Downvotes

A downvote indicates concerns about the review. Depending on project configuration and reviewer requirements, downvotes can prevent a review from being approved until the concerns have been addressed.

Stale votes

When a review is updated, existing votes can become stale. Votes become stale when:

• Files are added or removed.

• File content changes.

• File types change.

Votes become stale because reviewers approved a previous version of the review and must evaluate the updated review content.

When votes become stale:

• Vote counts are reset.

• Existing votes remain visible for reference.

• Reviewers must vote again on the latest review version.

You can only vote on the latest version of a review. If you attempt to vote on an older version, P4 Code Review prompts you to refresh the page.

Approval rules

A review can only be approved when all applicable approval requirements have been satisfied.

Approval requirements

Approval requirements can include:

• Reviewer votes.

• Required reviewers.

• Moderator approval.

• Workflow rules.

• Checklist requirements.

To learn more about checklist approval requirements, see Approval blocking.

To learn more about workflow behavior, see Workflow merging.

Minimum upvotes

Projects can be configured to require a minimum number of upvotes before a review can be approved.

Required reviewers

Reviews with required reviewers cannot be approved until all required reviewer requirements have been satisfied.

Moderator approvals

If a review is associated with a moderated branch, only a moderator can approve the review, even if all required reviewers have already approved it.

State restrictions

State transitions can be restricted by moderation rules, workflow rules, and user permissions. Not all users can move reviews into all states.

In projects without moderation:

• Review authors and project members can change review state.

• Users and groups configured to bypass workflow rules can also transition review states.

To learn more about review state controls available to users, see Change state button.

Self-approval

By default, review authors can approve their own reviews.

Projects that use moderators can impose additional restrictions on self-approval, and administrators can globally disable self-approval using the disable_self_approve setting. To learn more, see disable_self_approve.

Checklist restrictions

Checklist items can block approval.

By default, reviews cannot be approved if a checklist item has a status of:

• Fail

• Error

If reviews are configured to use AI-assisted checklists, checklist results can affect whether approval options are available.

To learn more about checklist statuses and AI-assisted checklist reviews, see:

• Checklist statuses

• AI review

Approval after review changes

By default, an approved review returns to Needs Review if the review content changes after approval. This occurs when files are added, removed, modified, or have their file types changed.

To learn more about review versions and review updates, see Review versions.

Approve and Commit

For pre-commit reviews, Approve and Commit allows a review to be approved and committed in a single action.

The option is available only when:

• The review satisfies its approval requirements.

• The review is a pre-commit review.

• Approval is permitted by project rules.

If reviews are configured to prevent approval when open tasks exist, Approve and Approve and Commit are unavailable until the tasks have been addressed.

To learn more about tasks and approval blocking, see:

• Open tasks

• Approval blocking

Next steps

• Code review features - To learn how reviewers interact with review pages, files, comments, and tests.

• Review process - To learn how processes affect approvals and review state transitions.

• Advanced concepts - To learn more about review versions and approval behavior.