ChangeLog: Office Document Review, New Draft Banner, Actions Rewrite

Welcome back to ChangeLog, where we dive into the latest developments around Review Board, Power Pack, and other Beanbag products.

Today we’re going to cover a major feature coming to Power Pack, plus some work that’s in progress for Review Board 6.

Office Document Review in Power Pack

Power Pack has long offered support for reviewing and diffing PDF documents. This has been used by companies to review documentation, contracts, schematics, industrial designs, and more.

Soon, you’ll be able to review a few more file types:

  • Microsoft Office documents (Word, Excel, PowerPoint)
  • OpenOffice/LibreOffice documents (Writer, Calc, Impress)
A sample review session for a LibreOffice Impress document, covering a presentation titled "Writing Enterprise WebApps in Bourne Shell." There's a comment saying "This seems like a really bad idea." The second page says "Bourne Shell: Why Not?" and states "It's on every system; It's memory-safe; You might not completely nuke your system unexpectedly, maybe."

It also supports diffing! You’ll be able to view the differences in new revisions of Word documents, spreadsheets, and presentations.

A screenshot showing a side-by-side diff of two PowerPoint presentations. The old text, "You definitely won't completely nuke your system unexpectedly" is shown on the left in red. On the right, the replacement text is shown in green: "You might not completely nuke your system unexpectedly." The red and green show only the changed words.

This will require setting up a small microservice, which we’ll provide via Docker.

When uploading a supported document to Review Board, Power Pack will send it along to the microservice to convert to PDF for render. This supports not just showing the document, but diffing multiple revisions of the document as well.

Both the original document and the PDF can also be downloaded to the local machine.

We’re expecting this will be released in Power Pack 6 by early/mid-2023.

The Unified Draft Banner

Over the years, we’ve come up with all sorts of ideas for improving the review experience in Review Board, and in Review Board 6, we’re kicking some of our plans into action, starting with the Unified Draft Banner.

This replaces the current, basic draft banners shown on review requests and reviews with a new one that:

  • Helps you see what all you have pending to publish (review requests, reviews, replies).
  • Let’s you publish them either all at once (with one combined e-mail) or individually, as before.
  • Shows additional information on what you’re reviewing, like the list of files in the diff viewer.
  • Can be further augmented by extensions.

When creating a new review request, the banner will look pretty similar to today:

Basic draft banner shown when posting a brand-new review request. This states the review request is a draft, and includes a combo Publish/Options button, followed by a Discard button.

When you have multiple things in flight (such as review request updates and replies to reviews), you can publish them in one go:

A draft banner showing that there are both changes to the review request pending, and one reply to a review. This lists "Changes an 1 reply" as a drop-down menu for selecting just a subset; a "Publish All"/Options combo button, and a "Review" drop-down menu. On the next line is a "Describe your changes" field for describing the new review request draft.

Or you can switch to a specific draft to publish:

The drop-down for the "Changes and 1 reply" menu, showing each draft. These can be clicked. The items are: 1) "Review request changes", and 2) "Replying to David Trowbridge's review"

The gear menu controls options for your publishes (depending on what’s being published):

The drop-down options on the "Publish All" combo button. This shows a single "Archive after publishing" checkbox.

The “Review” menu will always be present, and can be used to guide users to creating a new review, adding general comments, and quickly posting a Ship It! review.

This is still in the early stages. We’ll provide some more screenshots as development progresses.

Actions Rewrite

Behind-the-scenes, we have the “actions” system, which lets Review Board and extensions register buttons in some parts of the review request UI. It’s where the “Ship It!”, “Close”, “Upload Diff”, etc. buttons all come from.

The current list of review request actions. This shows: "Star", "Archive", "Close" menu, "Update" menu, "Download Diff", "Add General Comment", and two tabs: "Reviews" and "Diff".

The existing system is, let’s be honest, a bit of a mess. It grew organically, and we kept bolting things onto the design. There are class-based review request actions, dictionary-based review request actions, two forms of header actions, and several other purpose-built types. Keeping this maintainable has been a problem.

So this is finally getting a major overhaul. The new design is a lot more reasonable for both us and extension authors to work with. With this, we’re aiming for:

  • Better keyboard shortcuts throughout the product.
  • Improved accessibility.
  • Newer UI features like a possible Command-K bar (a sort of command-line-in-browser interface, similar to macOS Spotlight, Alfred, and other tools).

Once this is further along, we’ll have more to show off.

Looking Toward Review Board 6

With Review Board 6, we’re heavily focusing on improvements to the review process. There’s more to talk about, but we’ll save those for a future ChangeLog (available on this blog, Reddit, Mastodon, Twitter, or Facebook).

We’re aiming to for a mid-2023 release date for Review Board 6. This is a shorter release cycle than most of our large releases, and that’s the plan going forward. We want to get new features our faster, with smaller, focused releases.

Read More

Power Pack 3.0: PDF Diffs and License Updates

The new major release of Power Pack 3.0 brings the ability to diff PDF documents, comparing how the text of the document changes between revisions, and makes it easier to manage your license subscriptions.

Viewing Differences in PDFs

This can drastically cut down on the time needed to read through documents as the author takes in suggested edits from reviewers. Just like a code diff, any text changes made in a document are shown inline in the PDF, color-coded for easier viewing.

A handy new sidebar view catalogues all the changes made throughout the document, so there’s no need to carefully scrutinize as you scroll.

If you do need to scroll, a new “Lock scroll” checkbox gives you control over whether the documents should scroll in sync, or scroll individually.

In order to enable diffing support for PDFs, you will need a PDF document that contains text information embedded in the document (such as when printing to PDF or using OCR on a scanned document). It’s also important to update the existing PDF file attachment with the new document, instead of creating a brand new upload.

Easier License Management

We’ve revamped the Power Pack configuration page to better show the status and health of your license, how quickly the expiration date is coming up or whether you’re hitting your user cap.

The new “Manage your license” button takes you straight to our license portal where you can renew your license, convert to a yearly subscription, add additional users, and more.

Power Pack now checks for updates to your license automatically when viewing the Power Pack configuration page, and will install any new license it finds. You no longer need to download and install new license files from the license portal yourself.

Plus the Usual Bug Fixes

We’ve sorted out some crashes and visual glitches in reports, as well as a compatibility problem with AWS CodeCommit. The full list of changes are in the release notes.

Get started today with a 30 day trial license. After 30 days, enjoy a complimentary license for up to 2 users forever, or purchase a license for the rest of your organization.

Read More

Review everything, not just code

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.

Image Review

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.

Text Review

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.

Markdown Review

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.

PDF Document Review

So in conclusion…

Review all the things!

Read More