A new stopwatch extension for Review Board

In any business setting, it’s nice to measure as many data points as possible in order to optimize processes. One common request we’ve had over the years has been the ability to know how much time people are spending on code reviews. This can be used to identify problems on both ends of the spectrum. If people are knocking out reviews in just a few seconds, they’re probably not giving the code the attention it needs to find the defects. Likewise, if code reviews are eating up too much time, it can point to problems of accumulated technical debt or the need for training or mentoring.

Stopwatch Extension

We’re working on a new extension that adds a “stopwatch” to the bottom-right of a review request. This can be toggled on and off, and the total time will be recorded in the review. This data is also available in the API for use by external tools, and we’ll be adding some nice reporting of this data to Power Pack.

Stopwatch Extension - Review header

Read More

New Beta Release: Review Board Power Pack

Review Board Power Pack

Until now, we’ve been running two separate beta programs for PDF Review and “Review Board Enterprise”. We’ve decided to merge these together into a single product that we’re calling the “Review Board Power Pack.”

The major features of the combined package are:

  • Review PDF documents that are attached to review requests, commenting directly on the text, all in the browser with no extra plug-ins.
  • GitHub Enterprise support.
  • The ability to add capacity to your Review Board server by adding additional front-end servers.

Changes in the new preview

In addition to merging together the features of our two previous beta packages, there are some improvements and bug fixes for PDF Review in this release:

  • The outline mode in the sidebar now shows the tree structure of the table of contents.
  • When a document has a table of contents, the sidebar now allows switching between either the outline mode or the pages mode.
  • Scrolling behavior when using the mouse wheel or touch-pad gestures has improved significantly, making it easier to get all the way to the bottom of the document.
  • Non-PDF documents like .docx are no longer detected as PDF.
  • When attaching a PDF file with drag-and-drop, you can now click on the thumbnail to jump to the review UI to preview the document.
  • Several issues with PDF rendering have been fixed.
  • A fair amount of visual design polish.

pdf

Getting the Power Pack

If you already signed up for the beta, you should have an email explaining how to install it (or upgrade from the first beta). If you haven’t signed up, but would like to participate, please fill out our sign-up form and we’ll be in touch.

Once we have a final release, these features will be available on RBCommons.com for our larger tiers.

Read More

PDF Review Beta 2

A few weeks ago, we did our first private beta release for an extension for collaborative peer review of PDF documents. If you haven’t seen it yet, we encourage you to check out the original announcement, which explains the basic workflow.

Since that first release, we’ve received a lot of great feedback, and have been working hard to improve it. We’re proud to announce a new beta release, with several significant improvements:

  • Continuous scroll through the document!
  • Significant performance improvements when switching between pages.
  • Review emails now contain the selected sections for each comment.
  • Comments on the “Reviews” page and in review emails now link to the relevant page in the document.
  • Improved interaction when dragging out comment areas.
  • Improved visual layout, maximizing the amount of space for the document.
  • Fixed an issue where the page would continually make requests to the server when thumbnail storage fails (for example, if the PIL version on the server can’t handle PNG compression).

pdf-continuous-scroll

If you already signed up for the beta, you should have an email explaining how to install it (or upgrade from the first beta). If you haven’t signed up, but would like to participate, please fill out our sign-up form and we’ll be in touch.

Read More

Building a culture of code review

One question that we see pretty often is how to create an engineering culture that embraces code review. It’s hard to overstate the benefits of code review, and engineering groups who aren’t doing it are missing a huge opportunity to improve the quality of their software, as well as get a lot of other benefits.

Jeff Atwood of Coding Horror summarized a lot of these benefits in his article Code Reviews: Just Do It. His only caveat was “The only hurdle to a code review is finding a developer you respect to do it”. If you’re a one-person shop, then that’s a very hard question, but most of us work with developers we respect: our coworkers.

Unfortunately, getting engineers to change their workflow and processes is a lot like herding cats: generally impossible, except in the case that it makes their lives easier (and then they’ll herd themselves). One of the best managers I ever had explained to me her observation that people only change if they want to, and so the best approach to effecting change is to work on making them want it.

The extensive benefits of code review make it an easy sell, but if it’s not introduced in the right way, it can create tension and resentment, which will kill any chance of adoption.

The easy answer to creating a code review culture is to build it in from the start. Many of the startups that I’ve talked to recently have incorporated some form of code review from day one. Fortunately, a lot of new companies these days are founded by people who have worked in an environment where robust code review is a given, and when they strike it out on their own, it’s just the most natural way to do things. If you’re forming a new organization (or even a new group within an existing organization), it’s the ideal time to build in good practices from the start.

Where it becomes a sticky, difficult question is when dealing with an established company with entrenched practices. How do you get people to change the way they work? Anyone who has ever worked with actual humans will know that bursting in the door and announcing a new process is liable to be met with groans, laughter, or silent resentment (and often all three).

Sneak it in through the back door

Joel Spolsky has a lot of advice on how to get things done when you’re only a grunt, and a lot of that advice works very well for adding code review to existing processes. Going back to the psychology of change, it’s easiest to ask people to do code reviews for you, rather than the other way around. Dropping in on a coworker and asking them to take a look at your code before you check it in is received much better than dropping in on them and saying you’d like to have approval power over what they’re doing.

When I started working on the Workstation team at VMware, we already expected code reviews for every major change, but the official system used email. After creating Review Board, Christian Hammond and I wanted to use it at work as well as home, and we set up a server for ourselves. For the first couple weeks, we just sent things back and forth to each other, while still using the old process for everyone else. As the benefits of improved tooling became visible to others, it took off, and before we knew it, we had people we’d never even met using it.

If you’re a manager, don’t force it

For those of you who might be reading who are managers of software engineers, and want to add code review to your development process, I don’t have a ton of advice, because I haven’t done a whole lot of management. The biggest thing I can urge is to go slow and avoid prescribing any particular behavior.

Educate your employees, maybe set up some tools, and then try to let things happen naturally. Making code reviews a part of the way you measure performance is a nice goal, but doing so when people are still trying to figure it out incentivizes the wrong behavior. The more structure and process that’s enforced at the beginning, the less likely that code review will actually take root, or if it does, it will be a cursory process to get the rubber stamp.

Always remember that it’s not about ego

Ego in code reviews is a big enough topic that we’ll probably tackle it in a separate post, but I think it’s also worth mentioning here. When people are new to code review, it can feel like a brutal, ugly process. It kind of sucks to expose your hard work and have people tear it apart. A healthy code review culture requires respect on all sides–people reviewing code need to remember that there’s a human behind the code, and people asking for code reviews need to remember that they are not their code, and it’s only through collaboration that we produce our best work.

Read More

PDF Review Beta

A little while ago, we announced that we were building document review features for Review Board. This will be available as a commercial extension in order to help fund the project. Of course, once it’s ready, RBCommons customers will get it as part of their normal plans. I’d like to show off a bit what you’ll be able to expect.

Since Review Board 1.6, you’ve been able to attach arbitrary files to review requests. For anything except images, the only way to view them was to download them. You could add general comments to these files, but for large things like a document, you couldn’t use the direct commenting that we’ve all come to love from the diff viewer.

With the PDF Review extension, when you upload a PDF file, it gets a thumbnail and a “Review” link.

review-request

Clicking on this file will open up the PDF Review UI, which has controls to navigate the document. The file is rendered directly in the browser with no plugins (which requires a relatively modern browser).

pdf-viewer

Like image review (and screenshots before it), you can add a comment to the document by clicking and dragging over the area that you’d like to talk about.

adding-a-comment

When you publish, the areas that you selected will be copied into the review along with the page number on which they occurred.

review

If you signed up for the beta program already, you should have received an email with instructions on how to install and activate this extension. If not, feel free to sign up and we’ll get in touch!

Read More

Making RBCommons more inviting

We’ve just deployed a change that makes it much easier to get your team set up on RBCommons. Until now, if you wanted to add a new user, you’d have to register an account first, and then add the username in your team administration dashboard.

Going forward, instead of registering an account first, you can just add the email addresses of each of your teammates. They’ll get an email with a special sign-up link, and once they create their account, they’ll be automatically added to your team.

admin-users

As usual, if you have any questions or comments, feel free to get in touch.

Read More

Using checklists for code review

We’ve all seen them, and most of us make them. Process lists, to-do lists, lists of all kinds–there’s something very satisfying about checking a little box or crossing an item off a list. However, checklists can serve a greater purpose than as a physical reminder that we’ve accomplished something. In many fields, checklists exist because human brains are fallable and prone to distraction. Pilots use checklists to make sure that amid dozens of relatively simple tasks, none get forgotten. Checklists used before and during surgery reduced the death rate by nearly 50%.

I’ve been doing code review for a long time. In the open source world, code review happens on pretty much any third party contribution. In my time at VMware, pretty much every non-trivial change was expected to be reviewed before checking it in to source control.

In general, people are pretty good at the code review process, but it’s sometimes surprising what can slip through. A natural consequence of the way our brains look at the world is that it’s easy to pay a lot of attention to small details and code style flubs, and completely miss the big picture. It’s for this reason that a lot of designers will start with rough sketches when they start gathering feedback–if something looks too finished, reviewers will only give them comments about the details. Unfortunately, unless you’re starting out with pseudocode or architectural sketches, source code almost always looks “finished” and can therefore encourage some bad habits.

One of the ways that I avoid the pitfall of giving superficial reviews is with checklists. I have a bunch of different sets of checklists that I’ve developed and tweaked over the past few years, and for any given change, I’ll select the sections which apply. I’ve applied some of these at VMware, working on a large desktop application code-base (mostly at the user interface layer), as well as with Review Board itself.

Here are some examples of some of the many checklists I use in my day to day work:

(more…)

Read More