4 powerful tips for your Review Board dashboard

December 22, 2014December 22, 2014 Christian Hammond 2 Comments

The dashboard. It’s the very first thing you’ll typically see when you log into Review Board. Outside of review requests and the diff viewer, you’ll spend most of your time here – but are you getting the most out of it?

Did you know that you could close several review requests at once? Or see which review requests were specifically assigned to you, or the number of lines added/removed in each diff, or the bugs addressed, all at a glance? How about being able to keep track of activity on groups you’re not a part of?

Let’s go through some of the ways you can make the dashboard work better for you.

1. Choosing what information to display

Take a look at the top-right of the dashboard, at the very last column. See that pencil icon? If you click it, you’re going to see a list of all the columns you can put on your dashboard. You can turn some on, turn others off.

Depending on how old your account is, you may be using an older default set of columns, meaning you’re really missing out on some handy columns.

Here are my favorites:

Diff Size, newly introduced in 2.0 and on RBCommons, takes the latest diff on the review request and shows the number of lines added and removed. This gives me a good idea as to how long a review may take.
My Comments is a default now, but it wasn’t always. This displays a handy icon showing if you’ve already reviewed a change, if that review is still a pending draft, and whether you’ve said Ship It! Super helpful for sorting through your workload.
Select Rows, also introduced in 2.0 and on RBCommons, adds a little checkbox for selecting review requests. Selecting one or more lets you perform actions, which we’ll go into below.
Ship It! is your way of knowing if reviewers have deemed a change ready to ship, or if there’s any issues to resolve (on 2.0+ and on RBCommons). Green checkmark for Ship It, and yellow exclamation point for issues to resolve. If you don’t have this column, add it now!
Starred lets you click to star/unstar a review request. Starring is a way to keep tabs on the activity on a review request you’re not assigned to, CCing you on all e-mails and making the review request quick to find in the dashboard.
To Me simply displays a little indicator (») for any review request directly assigned to you. Usually a good place to start when deciding what to review.

Here’s how my dashboard looks:

2. Reorder your columns

Okay, now you have some new columns, and they’re all shoved to the right of the dashboard. That’s probably not where you want them. That’s okay, we can fix that.

You can re-order columns by simply clicking and dragging the column header. Move it where you want it, and the dashboard will remember.

Reordering Columns

I like placing all the little icons (Starred, My Updates, Ship It!, My Comments, and To Me) toward the left, right before the summary. Play around, see what works for you. Go nuts.

3. Sort your columns

You now have a lovely set of columns exactly where you want them. There’s some timestamps in there, maybe the repository or branch names. Now’s a good time to learn about sorting.

Certain columns can sort their data. Most anything with text, like Summary, Branch, or Last Updated, can be sorted. When you click a column, it’ll sort in ascending order. Click again to sort in descending. Click the “X” to unsort that column.

Sorting Columns

There are two levels of sorting. Click a second column, and everything will be sorted by that. If two rows have the same data for that column, then they’ll be sorted by the previously clicked column.

To prioritize changes going into a release, click Last Updated and then Branch. You’ll quickly be able to see review requests grouped by branch, then sorted by when they were last updated.

4. Close many review requests at once

Is your dashboard getting a bit messy? Did you forget to close a bunch of old review requests, and just hate the thought of going through and dealing with them one-by-one? Or maybe you’re an administrator and someone just left the company with a mess to deal with.

Remember that Select Rows column from before? It gives you a nice little checkbox for each review request. When you start clicking those checkboxes, the dashboard’s sidebar will begin to give you a summary of the review requests, along with options to close them all at once. You can discard them, or mark them as submitted into the codebase.

Dashboard batch operations

In one go, you can clear away dozens of review requests, making everyone else on the team very thankful, and completely in your debt.

Speaking of…

Next time, we’re going to talk about how to keep your dashboard squeaky clean, without micromanaging review requests. You’ll learn how you can put an end to messy dashboards once and for all.

In the meantime, Happy Holidays everyone!

Review everything, not just code

December 15, 2014December 28, 2017 Christian Hammond

Code review is a staple in many engineering cultures. The benefits to putting your code up for your teammates to scrutinize and critique are numerous. There’s the satisfaction of showing off your work to your peers and the comfort in knowing that any obvious flaws or bad design choices will be caught before they affect others.

Unfortunately, code review is often where thorough review ends for many teams. UI changes, mockups, PRDs, documentation, release notes, icons, and other visual components critical to a project are not always as closely inspected, or at least are not done so as part of the existing code review process. By leaving these out, or doing them out-of-band (e-mail, in-person reviews), or even by going through entirely separate tools, there’s the risk of missing and tracking valuable feedback.

Through Review Board and Power Pack, you can review those just as easily as code. No new tools to learn, no loosely tracked discussions. Here’s how.

File attachments on Review Board

In Review Board, you can attach any type of file to a review request and review.

There’s built-in support for general text-based file attachments, Markdown files, and images. Extensions can supplement that with support for reviewing additional file types, like PDF. Unsupported binary files can still be reviewed by downloading the file and then leaving a comment on it.

All you need to do to attach files is to drag them (as many or as few as you want) from your file manager right onto any new or existing review request.

Or, if you’re a command line junkie like I am, check out tip #3 on our 5 tips for RBTools.

You’ll be able to try these yourself on our demo page.

Reviewing screenshots, icons, and other images

If you’re developing a UI for your application, make sure your fellow engineers or your usability team sees it before your QA team or users do.

Take a screenshot, or two, or a dozen. Show off all the changes you made, the new dialogs, the icon updates. Upload them as part of your code change so that your reviewers can see the impact of your code. Your reviewers will then be able to go through your screenshots and review them just like source code.

Reviewing images is easy. Simply click-and-drag over an area of the image, like you’re selecting it. A comment window will pop up (just like for code). Enter some text and save it. When the review is published, you’ll see that section of the image in the review, and discussion can begin.

Reviewing plain text files

As developers, we love plain text. We have one-off bits of test code not fit for the tree, we have log files, development notes, test runs. All kinds of things that your reviewers may find useful when looking at your code.

So post them.

Reviewers will see a nice display of the text similar to what they’d see in the diff viewer. If Review Board recognizes the file type, it’ll even syntax highlight it for you, which is great for files like XML.

Reviewing Markdown files

Markdown is a pretty popular way to write rich, formatted text in the comfort of your 1970s text editor. I’m using it right now to write this post, in fact, and you may be using it for your documentation or Wiki pages.

During review, we automatically render your Markdown so that you can see how it looks. Reviewers can leave comments right on the rendered copy or on the raw Markdown text.

Want to see this in action? Check out our demo.

Reviewing PDFs or other documents

Product managers and doc writers generally aren’t writing Markdown or code. They’re working in Word, Excel, Power Point, or something more specialized. When they want a review of the latest PRD or section of the manual, they probably just e-mail it out to you, and you probably e-mail them back some replies. Yuck.

Instead, convince management and your doc writers to export their documents as PDF, and then upload them to Review Board. If you have Power Pack installed, or you’re an RBCommons subscriber on a Medium plan or higher, you’ll be able to read through the PDF and comment on any part of it.

This works very similarly to screenshot commenting. Click-and-drag to select a region, and leave a comment. That section will appear along with your comment in the review, just like with code or screenshots.

It’s a much better way of tracking all the feedback around the design or documentation of your product.

You can see what PDF review is like over on our demo page.

So in conclusion…

5 Tips for your RBTools workflow

December 8, 2014December 18, 2014 Christian Hammond 1 Comment

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:

Practicing effective self-review

December 1, 2014December 1, 2014 Christian Hammond 5 Comments

It’s nearly midnight. The end of a long coding session. Your code seems to work pretty well; all tests pass and it doesn’t blow up when you use it. It was a hard-fought battle, and you’re feeling great! The only reason it’s not already in the product is because your team has fostered a culture around code review.

At this point, you may be feeling ready to just post your code for review and move on to something else, waiting for the feedback to roll in. Is that what you do? Well, stop it! You’re only making things harder for yourself.

Your first reviewer should never be another person. It should be you!

Self-review saves time and increases quality

A typical code review cycle can easily take anywhere from an hour to a couple days. If your code isn’t perfect and your team is thorough, you will go through at least one cycle with at least one developer.

Likely more, since developers are often distracted by the tiny problems (style issues, typos) and ignore the larger problems (algorithmic issues, design flaws, bigger picture tasks) when reviewing. Oh they’ll get to the larger ones, but it might take another full review cycle or two.

Self-review can save you at least one cycle. Maybe more. The other reviewers will get to spend more time focusing on the more interesting issues instead of the little flaws, making them more likely to want to review the code. Plus, it’s far easier to convince people to look at your code when they think they’ll get through it quickly.

Let’s summarize the benefits:

Your code lands faster.
The feedback is more useful.
People will think you’re awesome for not wasting their time and will bake you cookies as thanks. Probably.

Now let’s talk about how to do self-review well.

ProTips for self-review

You may be used to reviewing other people’s code, but it’s going to be a bit different reviewing your own. You’ve already built up a mental state of how your code works, and won’t be reading it for the first time. You’ll have a bit of a blind spot that other reviewers won’t have, making it more difficult to see the flaws.

You can do something about that. Here are a few tricks we’ve learned.

Review your code in your code review tool, not your editor.
This will help put your brain in review mode, and take you away from your editing environment. This little context switch can be enough to help catch problems you wouldn’t have seen before.
Wait to post the code for review.
If there’s no rush to land the code, wait a day, work on something else, and then come back to it. You’ll have paged some of it out of your head by then. You might be surprised by what you notice.
Re-learn, don’t remember, how your code works.
Pretend you’ve never seen your code before. Read the code line-by-line, character-by-character. Don’t make any assumptions. You may catch some confusing variable names, documentation, or bad logic this way.
Use checklists for code review.
Keep a checklist of problems to look out for. Your team’s style preferences, possible edge cases, possible memory leaks, exception handling… Anything you can think of that may apply to your changes, or that of your team’s. This will help take a load off your sleep-deprived brain.
Read documentation, comments, and displayed text out loud.
You should read through every error message, every piece of documentation, and every comment out loud. See if it makes as much sense as you thought when you wrote it. If it helps, try explaining it to a rubber duck.
Take the opportunity to write more documentation.

If your code is low on documentation/comments, this is a good time to write some. Go into detail, cover corner cases, or anything that may be valuable to another reviewer.

By being forced to write about your own code as you read it, you’ll not only help ensure your code does what you expect, but you’ll help other reviewers get through a review cycle much faster.

This also works pretty well for unit tests.

These are a few of our tips we use when reviewing our own changes. What are yours?