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 Perforce service'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 Perforce service 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 Perforce service 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.
When a review is started, Swarm creates a new changelist that has the same id as the new review. What happens afterwards varies:
-
If the review contains uncommitted work (the pre-commit model), Swarm puts a copy of that shelved work into the review's changelist.
-
Any time a review is updated with shelved work, in addition to putting a copy of the work into the review's changelist, Swarm also creates an archive shelf, to maintain a historic copy of the work.
-
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.