RBTools 0.7.2 is here!

It’s been just over a month since RBTools 0.7.1 arrived at stores near you (or probably not). That’s a whole month spent not upgrading RBTools, and we can’t have that. Plus, there were some good bug fixes and new commands we thought we’d send your way. So let’s not waste any more time. Here’s what’s in today’s release of RBTools 0.7.2.

We’ve fixed some issues working with Bitbucket/Beanstalk/Unfuddle. We’ve heard reports from users that posting changes against their Git repositories hosted on these services that just resulted in failure, so we’ve gone ahead and fixed that all up.

There are also two new RBTools commands for you to play with:

  • rbt login will log into RBCommons and store the cookie. rbt post and other commands will still do that, but it’s sometimes handy to have new users log in once in order to ensure they’re all set up properly.
  • rbt logout will log you out of your API session on RBCommons, and delete the cookie.

For the full list of changes, see our release notes.

Read More

RBTools 0.7.1 is released

Today’s release of RBTools 0.7.1 fixes up several issues found in this month’s big 0.7 release, and helps to increase performance when posting changes for review. There are also compatibility fixes for Windows, and improvements to the new Windows installer.

Some of the highlights include:

  • Unicode compatibility fixes when running on Windows.
  • CVS/Subversion diffs are once again generated from the current directory and not the root of the checkout.
  • Several fixes for the Windows Installer.
  • Support for invoking RBTools in a Bash shell on Windows.
  • Fewer API requests are needed to post changes for review.

For the full list of changes, see the release notes.

Read More

An effective RBTools workflow for Git

One of the beautiful things about Git is that you have so many ways of making it work for you. This is also one of the frightening things about Git, particularly if you’re just starting out. There’s loads of documentation and blog posts covering all the ways you can use Git to manage your code or shoot yourself in the foot.

A question we’re often asked is how Git is supposed to be used with Review Board or RBCommons.

“How should I post changes,” they ask. “How should I land them?”

“Well,” we say, “that’s up to you… but here’s how we do it.”

One branch per review request

Branches in Git are pretty great. They’re light-weight, and you can really choose when and how to use them.

What we like to do is have one branch for every review request we’re still working with. Maybe they’re branching off of master, or maybe off of another change you have up for review… doesn’t matter.

Create the branch, and create as many commits on it as you want. You’re going to post these all for review under one review request. For our example, we’ll use 2 commits.

$ git checkout -b my-branch-1 master
$ vim foo.py
$ git commit -a
$ vim bar.py
$ git commit -a

Now let’s create another branch off of that, and make one commit here. This will be for your second review request.

$ git checkout -b my-branch-2
$ vim foo.py
$ git commit -a

Your tree now looks like this:

o [my-branch-2]
|
o [my-branch-1]
|
o
|
o [master] [origin/master]
|

Great, let’s post!

We’ll post that first change for review (my-branch-1). Since it’s based off of origin/master, this will be easy (since by default, that’s what’s diffed against). We just post like so:

$ git checkout my-branch-1
$ rbt post
Review request #1001 posted.

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

Excellent. If you go to that first URL, you’ll see your summary and description filled in from your commit messages. You can edit these to your liking.

If your server has any default reviewers set up, they’ll be assigned. You might also want to fill in some bug, add some testing information. Do whatever you want to do there and publish the review request.

Now sit back and relax and… oh wait, you have a second change ready for review! Thanks to Git and RBTools, you don’t have to wait on that. Let’s post that one too.

$ rbt post my-branch-1..my-branch-2
Review request #1002 posted.

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

What you’re doing here is posting all the commits on my-branch-2 that were made since my-branch-1. No need to push my-branch-1 first, or really worry about it in any way.

You’ll probably want to set the Depends On field to point to your other review request, as a hint to any reviewers deciding which to review first.

Oh, here’s some short-hand. If you’re already on my-branch-2, you can make use of HEAD instead of spelling out my-branch-2. In this case, this branch only has one commit, so you could also leave out my-branch1... All of these are therefore equivalent:

$ rbt post HEAD
$ rbt post my-branch-1..HEAD
$ rbt post my-branch-1..my-branch-2

This is probably familiar to you if you’re used to Git. You can use any Git SHA/tag/branch/revision range you want when calling rbt post.

Note: If you’re posting against a remote branch other than origin/master, you’ll need to either pass --tracking-branch=myremote/mybranch on any RBTools command, or set TRACKING_BRANCH = "myremote/mybranch" in .reviewboardrc. The remote must match the configured repository on Review Board.

Need to make some changes? -u to the rescue!

So someone found a flaw in your otherwise perfect code. Happens to the best of us. In both review requests, you say? Okay, we’ll let that slide for now.

Let’s update the first change. Lots of options here. You can make a new commit with the fixes, or you can amend the commit.

If it’s just a fix made in a previously un-pushed commit, we like to amend. Your choice.

$ git checkout my-branch-1
$ vim bar.py
$ git commit -a --amend
$ rbt post -u
Review request #1001 posted.

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

Now on to the second. We’ll probably want the latest from my-branch-1 as well, so we can rebase or merge. We like to rebase when this stuff is still in flux and not yet pushed, and we like to merge when the history starts to matter (that is, when the code is in some kind of decent, landable shape).

Again, your call.

$ git checkout my-branch-2
$ git rebase my-branch-1
$ vim foo.py
$ git commit -a --amend
$ rbt post -u HEAD
Review request #1002 posted.

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

The -u flag updates an existing review request that matches your commit message. If you’ve modified the summary or description in any way, it may prompt you for any review requests that mostly match. Just say yes or no.

Great, publish those changes. Eventually the code will be perfect.

Got your “Ship It!”? Time to land!

RBTools 0.7 and higher comes with a nifty little command, rbt land. This command takes a branch, verifies that it’s been reviewed, and lands the changes.

Let’s land both of your branches, one after the other.

$ git checkout master
$ rbt land --dest=master --push my-branch-1
$ rbt land --dest=master --push my-branch-2

This will verify that my-branch-1 is approved (at least one “Ship It!” and no open issues). It will then merge my-branch-1 into master, push it, and delete the old branch. Then it’ll verify, merge, push, and delete my-branch-2.

Each branch you land will be merged into master, with a merge commit containing the summary, description, bug numbers, and review request URL. If you want to instead squash each branch into a single commit on master, you can use --squash.

You can use --dry-run to see what will happen without actually changing your tree. Useful when you first start off.

You can also edit the commit message using --edit, or leave out --push if you don’t want to push the branch, or add --no-delete-branch if you don’t want to delete the branches. You can also set the default branch to land into. The documentation goes into all the options that are available.

Closing out landed review requests

We like to set up our review requests to auto-close when pushing commits. This is designed to work with rbt land.

When you land a change, the commit message will contain a line saying something like:

Reviewed at https://reviewboard.example.com/r/1001/

The auto-close hooks will see that and automatically close your review request, so you don’t have to.

And that’s how we do it.

There’s really a lot of options here. Some people push changes and then use the web UI to post them for review. Some people generate their own diffs and upload them. Some like to merge their own branches.

That’s all a lot of work, though. Our method give us:

  • Nice code organization, since every review request has its own dedicated branch.
  • Fast posting and updating of review requests.
  • Less mess. No extra branches sticking around, and review requests are automatically closed.
  • Confidence that every landed change has been approved. No slip-ups with pushing the wrong branch.

Give it a try!

Read More

Composing workflows using aliases in RBTools

RBTools 0.7 introduced support for aliases, a handy way to simplify common tasks and workflows when working with source code and review requests.

With aliases, you can write your own RBTools commands that expand into, well, anything. They could be a set of common options for an existing command, or they could call out to shell commands.

You can define your own aliases for your personal use, but you can also define aliases for your entire team. Since they live in .reviewboardrc, aliases can be committed to your repository for everyone to use. This is quite powerful, as it can help to easily standardize workflows for your whole team.

I’m going to show you a few ways to compose workflows using aliases.

Simplify posting code for review

Feature branches in Git are great. They help you to stay organized when you have lots of changes that depend on each other. If you’ve made heavy use of them, you’ve probably used this workflow a bit:

# Post some code...
$ rbt post HEAD

# After making some changes to code...
$ rbt post -u HEAD

# After making some changes to the commit message...
$ rbt post -g yes -u HEAD

There aren’t a lot of parameters there, but you still have to remember them and type them every time. The -u HEAD or the -g yes -u HEAD gets repetitive.

Let’s add a few nice and short aliases in ~/.reviewboardrc:

ALIASES = {
    # Post this
    'pt': 'post HEAD',

    # Post this and update
    'ptu': 'post -u HEAD',

    # Post this, update, and re-guess the description from the commit message
    'ptug': 'post -g yes -u HEAD',
}

Now the workflow becomes simply:

# Post some code...
$ rbt pt

# After making some changes to code...
$ rbt ptu

# After making some changes to the commit message...
$ rbt ptug

Much shorter, and hopefully easier to remember.

Run unit tests before posting code

If your project has a unit test suite, you’re probably supposed to run it before posting code for review. It’s easy to forget, or to just ignore it, since it’s another step in your process. We can solve both of those problems.

Say your project has a ./scripts/run-tests.sh that runs your test suite and outputs 1 for failure, 0 for success. Let’s make an alias that ensures tests pass before posting, and we’ll even pre-populate the Testing Done field with a message stating they pass. Let’s call this p for short.

ALIASES = {
    'p': '!./scripts/run-tests.sh &&'
         'rbt post --testing-done="Unit tests pass." $*',
}

Now you’ll never forget to run tests, and you’ll even have less to type.

ProTip: Define this as an alias in the .reviewboardrc in your repository, and switch your team to use that instead of rbt post.

Sanity-check patches on a review request

If you’re the gatekeeper for your project’s code (perhaps you’re an open source developer?), you need to test the patches that other people write before landing them. Thanks to rbt patch, you can easily pull down a diff from a review request and apply it, but you still need to run your tests before landing it. You also need to be careful not to disturb any changes in your own tree, or to test on the wrong branch.

To really sandbox your testing, your ideal workflow may look something like this:

$ git clone -b master . /tmp/test-project-<review request id>
$ cd /tmp/test-project-<review request id>
$ rbt patch <review request id>
$ ./scripts/runtests.sh
$ cd -
$ rm -rf /tmp/test-project-<reviw request id>

Let’s make an alias for this:

ALIASES = {
    'test-patch': '!rm -rf /tmp/test-project-$1 &&'
                  'git clone -b master . /tmp/test-project-$1 &&'
                  'cd /tmp/test-project-$1 &&'
                  'rbt patch $1 &&'
                  './scripts/runtests.sh &&'
                  'rm -rf /tmp/test-project-$1',
}

Now you have a quick and easy way to check any patch applying to the repository you’re currently in, without messing up your repository, typing a bunch of commands, or worrying about directories.

Screenshot a window and attach it in one go

If you’re doing UI work, you’re posting screenshots a lot. This means taking a screenshot, saving it somewhere, and drag-and-dropping it into a review request with a caption.

Let’s get that down to one command.

Now, different operating systems have different tools for capturing a screenshot. I’ll show an example for MacOS X and another for Linux. For Windows, you’ll need to grab a command line screenshot tool.

ALIASES = {
    # For MacOS X:
    'attach-screenshot': '!screencapture -wo /tmp/screenshot.png &&'
                         'rbt attach --caption "$2" $1 /tmp/screenshot.png &&'
                         'rm /tmp/screenshot.png',

    # For Linux:
    'attach-screenshot': '!import /tmp/screenshot.png &&'
                         'rbt attach $* tmp/screenshot.png &&'
                         'rm /tmp/screenshot.png',
}

Now uploading a screenshot is quick and easy! To upload to review request #123, just run:

$ rbt attach-screenshot 123

You can even attach a caption or custom filename, like so:

$ rbt attach-screenshot --caption="About dialog" --filename=about-dlg.png 123

Share your workflows!

We’d love to hear about any workflows you come up with. Send them along. We may even feature them in a future post or as samples in the documentation!

Read More

RBTools 0.7 is here!

RBTools 0.7 is packed with new tools and improvements for your workflow, making it faster to install, post changes to RBCommons, and land your changes.

There’s a lot here, so we’ll go into the major new additions.

Easy installation for Windows and MacOS X

We’ve improved the installation experience. If you’re on Windows or MacOS X, you can simply download the RBTools installer for your platform. In seconds, you’ll be ready to use the latest RBTools.

Land reviewed changes with one command

The all-new rbt land is the fastest way to take a change (in a local branch or a review request), validate that it’s been reviewed, and land it in your repository. It will format the commit message to include the review request’s description and testing information, and can even handle pushing the change upstream and deleting the local branch in one go.

(This is currently only available for Git repositories. Support for other repositories will come soon.)

Exclude files from review

Sometimes you’ll have modified files that you just don’t want up for review. Auto-generated code, for instance. You can now exclude these when posting changes for review by using the new -X option to rbt post, or by setting EXCLUDE_PATTERNS in .reviewboardrc.

Make your own commands with aliases

Ever find yourself repeating a group of options? rbt post -g yes -u HEAD, for instance? In 0.7, you can create an alias — a new RBTools command, basically — for those options.

You can even go a step further and make an alias that runs non-RBTools commands. Want to always run unit tests before posting code? Make an alias. How about merging the latest upstream changes into your branch before posting? There’s another alias!

See the documentation on aliases for more information.

Faster communication with RBCommons

We’ve sped up RBTools by caching results from RBCommons. This means lots of operations, such as posting changes, is faster than ever.

If you’re using the RBTools Python API to write your own integrations, you’ll benefit from this with no additional work on your end.

And lots more!

We haven’t even talked about rbt stamp, support for API tokens, or all the bug fixes and other feature improvements.

Check out the release notes for the whole list of changes.

Read More

5 Tips for your RBTools workflow

If you’re a Review Board or RBCommons user, you’re probably familiar with RBTools, our handy set of command line tools for working with Review Board. (If you’re not using RBTools, I’m going to tell you how to get started with it in a bit.)

You’re probably most familiar with rbt post, or post-review in older versions. This is the tool that helps you quickly get a change onto Review Board, or to update an existing review request. It’s pretty handy, but how much do you really know about it? Or about the other commands included with RBTools? (Yes, there are others!)

I’m going to show you five of my favorite tips and tricks for RBTools that you may not know about.

5. Opening a browser after posting with rbt post -o

When you run rbt post, you usually get something like this:

$ rbt post
Review request #123 posted.

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

Those links for opening the review request or diff are useful, but you can save yourself a step by having RBTools open your browser for you. Just pass -o to rbt post, like so:

$ rbt post -o

Your browser of choice will open, ready for editing. Want to do that automatically, every time? Add this to your .reviewboardrc in your home directory:

OPEN_BROWSER = True

4. Check your open review requests with rbt status

At some point or another, you’ll want to see what review requests you have open, either as a draft or currently pending review. I myself need to do this at times to help me remember if I’ve already posted something for review.

Sure, you could dig through the dashboard and check. That works great, but it means leaving the command line. That’s where the rbt status command comes in:

$ rbt status
   r/6676 - Add release notes for Review Board 2.0.12.
   r/6258 - Add release notes for Review Board 2.1 beta 1.

rbt status will show you all open review requests for the current repository – their IDs and their summaries. Pass --all and it’ll show you all open review requests across all repositories.

3. Attach files to review requests with rbt attach

Review Board makes it pretty easy to drag-and-drop files onto a review request in order to quickly upload them, but it does mean having the file manager and web page open. If you’re a command line junkie like me, you’d probably rather avoid that as much as possible.

rbt attach will let you upload a file to a review request with a single command. Just give it the review request ID, the file to upload, and an optional caption, and you’re done.

Let’s try it.

$ rbt attach 123 screenshot.png
Uploaded screenshot.png to review request 123.

Want to give it a caption?

$ rbt attach --caption "UI screenshot" 123 screenshot.png

2. Apply a review request’s diff to your tree with rbt patch

If you’re an open source developer, or you like to thoroughly test other people’s patches as part of reviewing their code, then this tip is for you.

rbt patch pulls down the latest patch (or a specified revision) from a review request and applies it to your tree. It can even create a commit for that patch, if using Git or Mercurial, by running rbt patch -c.

$ rbt patch -c 123
Changes committed to current branch.

We use this when accepting contributions from our own Review Board server. After a thorough review, we run rbt patch -c, edit the commit message as appropriate, and push it.

As a bonus, this will append a Reviewed at <url> line to the bottom of the commit message. If you’re using repository hooks to auto-close review requests (admins, see the “Hooks” link next to a repository in the administration UI), pushing this commit will take care of closing that out for you.

1. Easily update review requests with rbt post -u

If you’ve been using RBTools for a good long while, you’re probably used to passing -r <ID> to rbt post, in order to tell it which review request to update. This means having to look up the ID and making sure you don’t type it wrong.

In RBTools 0.6 or newer, we have a much simpler solution. Just pass -u. RBTools will automatically find a matching review request, asking if it’s not completely sure it’s a match, and update it for you. Let’s compare:

$ rbt post -r 123

vs.

$ rbt post -u

It’s much nicer. Get in the habit of using -u. It’s the wave of the future.

What if I’m not using RBTools?

Use it!

Seriously, RBTools is the best way to get the most out of Review Board. You can follow our installation instructions to get started. We’ll soon be announcing new installers to make this easier.

Learn more

The RBTools documentation is a great resource. You can learn about all the RBTools commands, our Python API for interfacing with Review Board, configuration options, and more.

We’ll be posting a new batch of tips and tricks for RBTools soon, plus some advanced Git and Review Board tips.

If you’re not already on our mailing list, subscribe today to keep up with the latest releases, tips, and strategies.

And now, we’d like to leave you with this:

Isn't it cute?

Read More

RBTools 0.6.3 is released!

Today’s release of RBTools 0.6.3 fixes a handful of annoying little bugs across Git, Mercurial, Subversion, Perforce, and ClearCase. If you use any one of these (and there’s a good chance you do), it’s time to upgrade!

In past releases, failed post operations could leave behind incomplete review requests, which wasn’t always obvious. RBTools will now print out the review request after a failure, making it easier to fix things up without creating a new review request.

We’ve also fixed a bug in the Python API for Review Board that resulted in errors when performing HTTP DELETE operations.

See the release notes for the complete list of fixes.

While this is a fairly small and bug-oriented release, we’re happy to announce that RBTools 0.7 is coming soon, with several new features and native installers for Windows and MacOS X!

Read More

RBTools 0.6.2 is released

This evening’s release of RBTools 0.6.2 fixes several bugs throughout rbt post and rbt patch.

Mercurial users will find that rbt patch now behaves as expected especially for Git diffs. No need to manually fetch and patch by hand anymore.

We’ve fixed some breakages that users hit with error messages coming from Review Board under certain conditions, and some compatibility issues with Perforce, ClearCase, and Git.

You can upgrade to RBTools 0.6.1 by typing:

    $ sudo easy_install -U RBTools

(If you’re on Windows, you shouldn’t need to type “sudo.”)

See the release notes for the full list of changes.

Read More

RBTools 0.6.1 is released

We have just released RBTools 0.6.1. This release improves upon April’s release of RBTools 0.6, fixing numerous bugs that have been reported to us over the past two months.

These fixes cover compatibility issues with different types of repositories, misleading or useless error messages, crashes in certain edge cases, and issues running on different operating systems.

You can upgrade to RBTools 0.6.1 by typing:

    $ sudo easy_install -U RBTools

(If you’re on Windows, you shouldn’t need to type “sudo.”)

If you’re running an older version, now’s a great time to upgrade! We outlined the major improvements in our RBTools 0.6 announcement.

See the release notes for the full list of changes in 0.6.1.

Read More

RBTools 0.6 is released

RBTools 0.6 has just been released, and it’s a big one. We spent a lot of time simplifying the process for posting and updating review requests, and we think it’s going to make life a lot easier for just about everyone.

Posting using Git or Mercurial used to require dealing with --parent and --revision-range, along with our custom revision syntax. Now all you have to do is pass native revisions or revision ranges to rbt post, like so:

$ rbt post HEAD
$ rbt post main-branch..feature-branch
$ rbt post 123:126

Compare this to the old way of doing things:

$ rbt post --parent=HEAD^
$ rbt post --revision-range=main-branch:feature-branch
$ rbt post --revision-range=123:126

We’ve also improved how “guessing” descriptions and summaries from commits work. In previous versions, you needed to run rbt post -g to enable guessing, but in 0.6, it’s now automatic for new review requests. This means less typing and less work to do.

That behavior can also be changed through new GUESS_FIELDS settings in .reviewboardrc. This is covered more in the documentation.

A few other goodies:

  • Feature and performance improvements for Mercurial
  • Git repository hook scripts for auto-closing review requests and requiring approval for pushes
  • Many new configuration options

And more.

A couple important notes. We’ve removed support for the old post-review tool. Running post-review will now tell you to use rbt post instead.

We’ve also removed support for Python 2.4. You will now need 2.5 or higher. We strongly recommend that everybody upgrades to Python 2.7.

See the release notes for the complete list of changes.

Read More