March 7, 2013

Reviewing and Promoting a Shelved Change in One Easy Step


In a previous article, I described how Perforce shelving can be used as a very lightweight code review system. The 2013.1 release adds the capability to directly submit a shelf, which simplifies the workflow for informal review processes. There's another change that supports a slightly more sophisticated code review system: the ability to unshelve a change to a different branch.

Here's the review process in a diagram.

shelving table

So in this scenario, either by convention or permission, I work on a task branch for some of my work. When I need review, I shelve my changes and assign the shelf to the reviewer. She unshelves to the integration branch so she can conduct a thorough review: examining the diffs, perhaps merging in newer work, building, and testing. Finally if everything is ok she'll commit the change on the integration branch, and I'd then pull the latest changes back to my task branch (or create a new task branch).

Here are some example commands with annotations at the interesting points.

p4 edit task\glob.c
//depot/task/glob.c#1 - opened for edit

# make my edits
> vim src\glob.c

# packaging changes for review
> p4 shelve
Change 12 created with 1 open file(s).
Shelving files for change 12.
edit //depot/task/glob.c#1
Change 12 files shelved.

# The reviewer unshelves, using a branch map to open the files in another branch
> p4 unshelve -b dev.b -s 12
... //depot/dev/glob.c - must resolve //depot/task/[email protected]=12 before submitting

# This isn't just overwriting the file on the other branch.  Based on
# the file history, Perforce is running a three-way merge to apply the
# shelved changes. 
> p4 resolve
dev\glob.c - merging //depot/task/[email protected]=12
Diff chunks: 1 yours + 1 theirs + 0 both + 0 conflicting
Accept(a) Edit(e) Diff(d) Merge (m) Skip(s) Help(?) am: am
//ws4/depot/dev/glob.c - merge from //depot/task/glob.c

Of course, unshelving to a new branch is also great if you just started working in the wrong branch.

Intrigued? There are a lot of possible review workflows that you can build around shelving. Grab the 2013.1 release and give it a try!