Using RBTools With Perforce¶

This guide covers how you can use RBTools to post changes to Perforce.

A typical workflow looks like this:

Create a changeset for each review request
Post your change for review
Make changes based on feedback and re-post for review
Submit your change to the depot
Close your review request

We’ll go over these concepts and then show you an example session.

Before you begin¶

This guide assumes the following are already set up:

An administrator has configured a Perforce repository in Review Board.
A .reviewboardrc file has been created and placed in your checkout location.
RBTools is installed and the p4 command line tool is in your system path.

Step 1: Create your change¶

Create your change using p4 change and open/add/delete any files you want included in the review request:

$ p4 change
$ p4 open -c <changenum> <filename>
$ vim <filename>
$ p4 add -c <changenum> <filename>
$ ...

Changes can optionally be associated with a stream.

You’ll want to populate the changeset with a summary and description. These will be used to populate the review request’s own summary and description.

Step 2: Post your change for review¶

Once you have a change with modifications to the depot, and you’re ready to post it for review, you can run post and include the change number:

$ rbt post <changenum>

For example:

$ rbt post 10291
Review request #123 posted.

https://reviewboard.example.com/r/123/
https://reviewboard.example.com/r/123/diff/

You can use the -o option to automatically open this review request in your web browser for editing.

The posted review request will be populated with your changeset’s summary and description. If you have default reviewers set up, they’ll be assigned.

Once you’re done filling out fields on the review request, click Publish to send it out for review.

Step 3: Update from reviewer feedback and re-post¶

Got some reviewer feedback to incorporate into your change? Easy.

Update the files in your change, and/or the information in your changeset.
Re-run rbt post to update your review request.

This will update the same review request already associated with your change number, and will also update the review request details (such as the summary and description) from the changeset description.
Update any information on the review request, if you want to.

We recommend describing the changes you’ve made, so reviewers know what to look for. The field for this is on the green draft banner.
Publish the new changes for review.

Step 4: Submit your change to Perforce¶

Once you’ve received approval to land the change, it’s time to submit your change. You’ll do this using the standard p4 submit:

$ p4 submit -c <changenum>

Step 5: Close your review request¶

Now that your change is in, it’s time to close your review request.

This might happen automatically, if your server and repositories are set up to auto-close review requests when changes are pushed.

This can be configured in Perforce using a custom Perforce change-submit trigger script.

If you’re not set up this way, no problem. You have two options:

Navigate to the review request and close it.

In Review Board 6 and newer, click Close -> Completed.

In Review Board 5 and older, click Close -> Submitted.
Run rbt close <review request ID> (see the documentation).

Putting it all together¶

Let’s walk through an example.

We’ll create a new change and make some modifications:

$ p4 change
<edit the changeset:>
...

Description:
    Add a change to do something great.

    Let me spend a lot of time explaining what this change is doing
    so that reviewers can fully understand it.

<save the changeset...>

Change 105 created.

$ p4 add -c 105 art/spritesheet.png
$ p4 open -c 105 src/engine/collision.cs
$ vim src/engine/collision.cs
$ p4 delete -c 105 docs/proposed-spec.txt
$ p4 move -c 105 src/utils.cs src/common/utils.cs

We’ll now post change #105 for review:

$ rbt post 105
Review request #1001 posted.

https://reviewboard.example.com/r/1001/
https://reviewboard.example.com/r/1001/diff/

That review request will be populated with your changeset’s summary and description.

Let’s create a second review request, covering a couple more changes.

We’ll take the opportunity to mark these as dependent on our new review request #1001:

$ p4 change
...
Change 106 created.

$ p4 add -c 106 art/character-model.png
$ rbt post --depends-on 1001 106
Review request #1002 posted.

https://reviewboard.example.com/r/1002/
https://reviewboard.example.com/r/1002/diff/

Meanwhile, we got some feedback on change #105/review request #1001, so let’s update our changes.
```
$ vim src/engine/collision.cs
$ rbt post 105
Review request #1001 posted.

https://reviewboard.example.com/r/1001/
https://reviewboard.example.com/r/1001/diff/
```
Go to the review request, describe the changes you made, and publish the new changes.
Tip

You can update, describe the changes (-m), and publish (-p), all in the same step:
```
$ rbt post -p -m "Fixed a broken link." 105
```
Hey, we got a Ship It! for both review requests! Great, let’s submit these and close out the review requests.
```
$ p4 submit -c 105
$ p4 submit -c 106
$ rbt close 1001
$ rbt close 1002
```
rbt close isn’t necessary if using a Perforce change-submit trigger script for the repository!

If a script is installed, the changes will be checked for approval before they can be submitted, and the review requests will be closed automatically:
```
$ p4 submit -c 105
$ p4 submit -c 106
```

You’ll get the hang of this process in no time. Soon you’ll be well on your way to better code quality.