Advanced concepts

Advanced concepts explain how reviews are managed internally, how review versions are created and maintained, and how P4 Code Review handles review content, branches, workflows, and storage.

Use this page to understand:

How review versions are created and managed.
How review content changes over time.
How append and replace operations affect reviews.
How reviews are represented internally.
How workflow and branch changes affect reviews.

Review versions

Each time a review is updated, P4 Code Review creates a new review version.

Review versions provide a complete history of the review and allow users to examine how review content has changed over time.

Each review version is associated with the changelist used to create that version.

Version history

A new review version is created when:

Files in the review are updated.
A changelist is appended to a review.
Review content is replaced.
Review content is reverted to an earlier version.

Review versions are retained so that users can view the history of a review and understand how the review evolved.

Reverting review versions

Reverting a review creates a new review version.

The review content matches the selected earlier version, but the review version number is incremented.

For example:

Version 1
Version 2
Version 3

Revert to Version 1

Result:
Version 4 contains the same content as Version 1

For an example of reverting and repairing review content, see Fix a review if it has been replaced with the wrong changelist.

Votes and review versions

Votes are associated with a specific review version.

When review files, file contents, or file types change:

Votes become stale when review files, file content, or file types change because reviewers approved a different review version.
Vote totals are reset.
Reviewers must vote on the updated review version.

Users can only vote on the latest version of a review.

To learn more about stale votes and approval behavior, see Stale votes.

Comparing review versions

Review versions can be used to understand how review content has changed over time.

Use the version selectors on the Files tab to compare review versions. To learn more, see Review version selectors.

Examples include:

Identifying when a file was added to a review.
Determining when content was replaced.
Reviewing changes made by multiple contributors.
Locating the version that should be restored when reverting a review.

For examples of how review content evolves between versions, see:

Internal representation

P4 Code Review stores reviews using changelist-based data structures that allow review content to be versioned, updated, and rebuilt over time.

Review content

A review is not limited to a single changelist.

A review can contain content from:

One changelist.
Multiple pending changelists.
Multiple committed changelists.
A combination of pending and committed changelists.

As changelists are added, appended, or replaced, P4 Code Review creates new review versions that reflect the current review content.

When multiple revisions of the same file are added to a review, the most recent revision becomes the active review content.

To learn how review content is updated using changelists, see Add changelists.

Stream specifications

A review can contain only one stream specification.

If a changelist containing a stream specification is appended to a review that already contains a stream specification, the original specification is replaced.

If the new stream specification differs from the original specification, P4 Code Review might not be able to display a comparison and displays File content unchanged instead.

Append mode and replace mode

Internally, reviews track how new content should be added.

Append mode

When a review is updated using #append-xxxx the review enters append mode.

Subsequent updates using #review-xxxx are appended to the review until the add mode changes.

To learn how append operations are performed, see Append a pending changelist to a review.

In append mode:

Existing review content is retained.
New changelist content is added to the review.
Newer file revisions replace older revisions of the same file.

For examples, see:

Replace mode

When a review is updated using #replace-xxxx the review enters replace mode.

Subsequent updates using #review-xxxx replace the existing review content until the add mode changes.

To learn how replace operations are performed, see:

In replace mode:

Existing review content is removed.
Review content is replaced with the contents of the new changelist.

For an example, see Advanced review process using #review, #append, and #replace in the changelist description

Review type transitions

The review type can change when review content is replaced.

Examples include:

Replacing a pre-commit review with a committed changelist creates a post-commit review.
Replacing a post-commit review with a pending changelist creates a pre-commit review.

This allows reviews to evolve as development and review requirements change.

To learn more about review models, see:

Workspaces and clients

P4 Code Review uses dedicated server-side workspaces to manage review content.

P4 Code Review Clients

P4 Code Review creates and manages its own workspaces when processing reviews.

These workspaces are used to:

Access review files.
Compare revisions.
Generate diffs.
Build review versions.
Process review updates.

Reviewers and authors do not normally interact directly with these workspaces.

Review data storage

Review content is stored independently from an individual user's local workspace.

This allows:

Multiple contributors to update the same review.
Review content to persist across review versions.
Review history to be reconstructed.
Review content to be restored when required.

Administrative concepts

The following concepts affect review behavior and are useful when troubleshooting unexpected review changes.

Branch inheritance

When review content introduces files from a new branch:

Default reviewers for the branch are added to the review.
Branch moderators become moderators of the review.
Branch workflow rules may affect the review.

When a branch is removed from a review:

Existing reviewers are retained.
Moderators associated only with the removed branch are removed from the review.
Branch workflow rules associated with that branch are removed.

To learn more about reviewers, moderators, and approval requirements, see Reviewers and approvals.

Workflow merging

If workflow enforcement is enabled and review content contains files from multiple branches, P4 Code Review merges the applicable workflow rules.

When workflows are merged:

Requirements from multiple workflows are combined.
The most restrictive workflow configuration is used.
Additional review requirements may be introduced as content is added to the review.

This behavior explains why review requirements can change after adding or replacing review content.

Internal review mechanics

When review content changes, P4 Code Review evaluates:

Review files.
File revisions.
Branch membership.
Workflow rules.
Review type.
Reviewer assignments.

Depending on the changes introduced, P4 Code Review may:

Create a new review version.
Mark existing votes as stale.
Add reviewers.
Add moderators.
Merge workflow rules.
Change the review type.

These updates ensure that review requirements remain consistent with the current review content.

To see these behaviors in practice, see: