Models

There are three code review models: pre-commit, post-commit, and the Git Fusion model. Which model you use for code reviews with Swarm is up to you.

Pre-commit model

The pre-commit model is possible due to the Helix Versioning Engine's shelving feature. Shelving enables you to temporarily make copies of your files available to other users without committing the changes into the depot. Shelving can be a very handy way for developers to create a backup, or to handle local workspace changes that might otherwise lose work in progress, without having to commit code that might destabilize a codebase.

Swarm uses the shelving feature in the Helix Versioning Engine to manage code reviews. Shelving allows reviewers to easily acquire a copy of the code to be reviewed, and allows updates to the reviewed code prior to submission.

Tip

For more information on shelving, see: P4 User's Guide: Shelving work in progress.

Post-commit model

The post-commit model can be used if your team's development processes preclude the use of shelving. Code must be committed to the Helix Versioning Engine before code review can begin, which reduces the opportunity to fix problems before, for example, a continuous integration system notices problems. However, code reviews can be started for any existing code regardless of how long it has been committed.

Git Fusion model

Perforce Git Fusion provides repo management for Git repositories, and provides workflows that enable Git and Perforce users to collaborate on the same projects using their preferred tools.

The Git Fusion model is similar to the pre-commit model; changes in your local repo can be pushed for review to a named Perforce branch in the Git fusion repo configuration, making your proposed changes available so that others can review and comment on them prior to committing them to the target branch. Git Fusion and Swarm work together to create a review branch and container for the pre-commit collaboration.

The Git Fusion model has several limitations that you should be aware of:

  • The target branch for Git Fusion-created reviews must be a fully populated branch, and must be listed in the repo-specific Git Fusion configuration.

    See "Setting up Repos" in the Git Fusion Guide for details on converting a lightweight branch into a fully populated Perforce branch.

  • Reviews created with Git Fusion can only be updated from Git Fusion.

  • You cannot clean up history and then push your changes to the same review. If you perform a Git rebase, you should push your changes as a new review.

  • A Git Fusion review does not currently display the individual task branch commits that make up the review. Only the merged commit diffs are shown.

Tip

For more information on Git Fusion, see the Git Fusion Guide

Internal representation

A code review consists of one or more shelved changelists that Swarm manages. A shelved changelist is a pending changelist that has a snapshot of its files on a shelf associated with the changelist.

When a review is started, Swarm creates a new changelist that becomes the review changelist. What happens afterwards varies:

  • If the review contains uncommitted work (the pre-commit model), Swarm copies the shelved files from the user's changelist that initiated the review into the review's changelist.

  • Any time that a user's changelist associated with the review has its shelved files updated, Swarm copies the shelved files into its review changelist and creates an archive changelist. An archive changelist is no different from any other pending changelist with shelved files, but it allows Swarm to provide versioning and diffs within a review.

  • If the head version of a review is committed (the post-commit model), the review's changelist is emptied of files.

The review's changelist is never actually committed; this allows the review to be opened later with additional shelved changes.

Important

Swarm's managed review changelists should only be deleted if you are uninstalling Swarm.

Swarm's review changelists maintain the history of a review and all of its feedback. The deletion of a Swarm shelved changelist causes instability and potentially data loss, and represents a scenario that can be very challenging to recover from, even with the engagement of Perforce consultants.

You can display a list of all of the Swarm-managed changelists using the p4 changelists command: 

$ p4 changelists -u swarm
Change 1212285 on 2015/07/31 by swarm@swarm-96017af4-5615-9819-7af1-6fc1fa537214 *pending* 'Add requirements and instructio'
Change 1212284 on 2015/07/31 by swarm@swarm-96017af4-5615-9819-7af1-6fc1fa537214 *pending* 'Add requirements and instructio'
...

Note: swarm is the userid with admin-level privileges within the Helix Versioning Engine that Swarm is configured to use.