An Introduction to RBTools

The best and easiest way to post patches to RBCommons is to install our RBTools suite of command line tools. This will come with a tool called "rbt post," which will post any in-progress changes from your local tree to RBCommons for review.


We have installers for Windows and MacOS X, as well as installation instructions for Linux. See the RBTools download page.


Workflow

The common workflow for posting changes using RBTools is:

  1. Prepare your local changes so that they're ready to be reviewed. (This will include committing to a topic branch if you're using Git, Bazaar, etc.)
  2. Run `rbt post` to post to RBCommons.
  3. Wait for reviews. Discuss any comments the reviewers may have for you.
  4. Make any requested changes to your code, if any.
  5. Run `rbt post -u` to update the review request with your new code.
  6. Rinse and repeat until you're ready to commit!

This is a pretty typical workflow, and is called a "pre-commit workflow." This means the reviews cover code before they're committed upstream.


rbt post also supports a "post-commit workflow," where changes already in the codebase are put up for review. For more information on this, see the documentation on Posting Committed Code.


There are many other capabilities in "rbt post." For the full breakdown of what it can do, see the rbt post documentation. You can see the full RBTools documentation for all the other tools that we ship.


Git and Branches

When using RBTools with Git, you have a few more options you may need to consider, depending on your branch setup.


Just running `rbt post` assumes that you want a diff between master..HEAD, and that your nearest remote tracking branch is origin/master. However, this may not be what you want.


Parent branches

If you're working on a topic branch (branch A) that's based on another unpushed topic branch (branch B), you may want to just put up branch A for review. To do this, you'll specify the revision range, starting at branch B. For example:

 

rbt post branchB..HEAD

 

If you just want to post the HEAD commit for review:

 

rbt post HEAD

 

Tracking branches

If your nearest remote tracking branch isn't actually origin/master, you'll need to specify an alternate tracking branch. Say, for example, that you're working somewhere off of origin/release-1.0.x. You would want to use --tracking-branch=origin/release-1.0.x.


Typing this every time on a branch is annoying, so there's a shortcut. Just modify the .reviewboardrc file on that tracking branch to include:

 

TRACKING_BRANCH = 'origin/release-1.0.x'

 

Commit that, and from then on, your tracking branch will be set correctly.


After posting your patch

When you post your patch using "rbt post", you'll be given the URL for your review request. It'll be set as a draft that only you can see, and you'll be able to make some changes before it goes out to your team.


You'll need to make sure the summary and description are what you want, and that you have at least one reviewer (either a user in your team or a review group) listed.


You may also want to describe the testing you did, or list the bugs you fixed. Maybe drag-and-drop some screenshots or files from your file manager onto the page to upload them.


Once you're satisfied, click "Publish," and it'll go out to your team!