ChangeLog: October 31, 2019 β€” DiffX, CSS Components, Admin UI

This week, we’re going to dive into three major topics:

  • DiffX, our proposed standard for a better Unified Diff format
  • Our new in-house CSS Components standard
  • The work being done on the Review Board Administration UI

DiffX

Unified Diffs, the most common type of diff files, are pretty lacking in standards. Nearly every type of source code management solution outputs its own version of a unified diff, shoving metadata into it however the developers saw fit. This frankly makes it a pain to work with diffs in Review Board, and I’m sure anyone else building similar tools can say the same thing.

A few years ago, we jotted down some ideas of what we’d like to see in diffs. We wanted:

  1. A superset of Unified Diffs that’s fully backwards-compatible (no way would a new diff format gain traction if existing tools couldn’t use it)
  2. A format that could be reliably serialized/deserialized (complete with metadata and file contents) as easily as something like JSON without writing a parser for a dozen different variations of the format
  3. Information on the encodings of a diff file and of the contents of a file, so we no longer have to guess
  4. Changes across multiple commits in a single file
  5. Some standard way of representing changes to binary files

We feel this is important. You wouldn’t believe how wildly different two diff files can be, and how broken most are (just having spaces in a filename means you’re going to run into all sorts of crazy problems).

So we put these ideas together and called it DiffX. Our plan was to build a specification, a standard Python library (and later libraries for other languages), and RBTools/Review Board support.

This week we put up the initial draft of the DiffX specification and documentation. Take a look. See what horrors tools like ours go through, and what we’d like to do about it.

Do you work on another code review tool or source code management system? Let’s talk!

Note that this is still a work-in-progress, and we have a lot we need to better formalize the parsing and the metadata format (and make a public, useful reference implementation).

CSS Components

During Review Board 4.0 development, we kept running into clashes between CSS rules, and had to deeply nest CSS classes and elements in order to ensure our styles would apply. Yuck. This was not sustainable.

We sought to fix this for our code, and looked into what others have done. We considered BEM, BEMIT, and a few other approaches. None felt quite right for our needs (particularly since we want to avoid clashes between third-party extensions).

So we took what we liked in each and drafted our CSS Component Style Guide.

This gives us a better way of thinking about what goes into our stylesheets and HTML pages. We think in terms of formal, reusable components, instead of just haphazardly tacking on styles for whatever HTML we’re writing.

We group together LessCSS variables (used for colors, sizes, etc.) and macros (for customizing a component’s presentation in a safe way) under organized namespaces. Stylesheets (ours and extensions’) that are looking to fit in with our styles or specialize a component can rely on these to better fit in.

We’re also taking care to add formal documentation for everything we add, which forces us to think about our styles, reason about them, and support them.

Want to see this in action? Here’s a few examples:

We’re still working on moving over to this, writing all new CSS using this standard and migrating old styles as needed. This is a long-term project, but we thought it might be interesting to some of you.

If you’re developing extensions for Review Board, we encourage adopting these new styling conventions. It’ll make your life so much easier.

The New Administration UI

Last week, we talked about the work on Python 3 and Django 1.11, and some of the huge tasks we’ve had to work through to support this.

One of the large — and final — hurdles is our administration UI. Django helpfully provides a built-in administration UI that projects get out of the box, and it’s very useful. And we extend and customize it heavily.

The problem is that Django’s administration UI has changed a lot since 1.6, and frankly it wrecked ours. So we’re rebuilding it, better than it was before.

Here’s a breakdown on the new UI:

  • It’s mobile-friendly
  • Organization is now much more clear — all navigation is in the sidebar, not split between sidebar and the top header bar
  • The administration dashboard widgets are so much better — larger, less cluttered, faster, and trimmed down to only the most useful widgets
  • It’s completely our own, no longer dependent on Django’s rendering, so future upgrades will be smoother

It’s also built with our new CSS component standard, and introduces new components that we can use throughout the product. Extensions can take advantage of these, too, helping them look like a native part of Review Board without worrying too much about our styling.

Here’s a couple in-progress screenshots.

Next Week

We’ll go over some of the new diff functionality being worked on in Review Board 4.0, and what we’ve been up to in RBCommons land.

Again, if you have any questions, or anything you’re curious about and want us to cover, please reach out on our community forum.

Read More

ChangeLog: New Integrations, Releases, and Prep for RBCommons 3.0

We’ve had a really busy couple of weeks since the last ChangeLog. There were two Review Board releases, a small setback with RB-Gateway, and lots of testing and infrastructure work for RBCommons 3.0.

Review Board 3.0.4 and 3.0.5

Last week, we put out Review Board 3.0.4, a feature-packed release introducing:

It was a pretty great release, fulfilling a lot of feature requests we’ve had for a while an providing the foundation for some new work we’re doing. Unfortunately, there was a last-minute error that, in production, broke part of the form for repository configuration.

Really embarrassing.

Now, we’ve found most people don’t upgrade the same day that a release goes out (downtime must be scheduled, people are busy, etc.) so we mostly started hearing about it two days later. As soon as we realized the mistake, we quickly got a new release out, Review Board 3.0.5, and put some changes in place to help prevent this sort of last-minute problem from happening again.

The good news is that, in the meantime, we went through and fixed a bunch of bugs that didn’t make the 3.0.4 release, but were ready for 3.0.5. So really, we’re just hoping we can all pretend 3.0.4 was just a pre-release for 3.0.5 now πŸ™‚

Review Board 3.0.6 is currently scheduled for April 10th. I’m expecting it to go smoothly.

RB-Gateway Difficulties and Delays

RB-Gateway, our API wrapper around Git and Mercurial repositories, was supposed to release, well, today. Sadly, that’s not happening.

Let me back up. RB-Gateway is written in Go, unlike most of our projects which are Python-based. Go was chosen partly due to concurrency benefits for handling and serving up requests, and partly for its ease of cross-compilation and distribution (just drop it into a directory and run it on any supported platform).

It’s the cross-compilation that posed a problem. We use git2go, a Go wrapper around libgit2, a C library for talking to Git repositories. We don’t need a lot from it, but it made sense to “go” with that (sorry).

Problem is, including a C library makes cross-compilation much harder, and there’s threads full of discussions on issues with compiling and utilizing git2go in production, depending on how it’s compiled and used. So we’re planning to remove git2go usage.

Instead, we’re evaluating other Git libraries. We probably won’t roll our own, but as we don’t really need much from a Go library, we’ll “go” that route if we need to (sorry).

When that’s done, we should be ready to release.

Prep for RBCommons 3.0

This Friday, we’re beginning an upgrade of RBCommons, bringing many of the features of Review Board 3.0 to the service. We’ve spent much of this week getting this ready — rebuilding servers, testing database migrations, running through checklists of manual feature tests, etc.

There’s going to be a lot to love in this release, but those following Review Board development will surely notice that some features (such as Slack, Asana, etc. integrations) will not be there on launch. We have just a bit more work to do before those are ready. We want those as much as anybody, so they’re high up on the priority list.

The blocker right now is that the administration pages for some of these features are built to plug into the Django administration page, not the custom RBCommons team administration page. So there’s still some work to do before that’s complete. Soon, though!

The upgrade should be smooth, and we should be back up in only a few hours, but just in case, we’re leaving the maintenance window open through Sunday. We aimed for a holiday weekend (well, holiday for a lot of people, anyway) to reduce the impact on users.

Read More

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

Extensions can now reference static assets from Djblets/Review Board

I’ve made some fixes to the extension packaging today that allow stylesheets in an extension to reference assets (images, fonts, other stylesheets) found in Review Board or Djblets. This wasn’t working before, due to some assumptions Django makes when it comes to post-processing and packaging of static files.

Django allows you to define a list of static namespaces with a given name, and any static path starting with that name is looked up in that resource. So, djblets/images/<blah> or rb/fonts/<blah>.

Works great in templates and everywhere else, except for static file packaging. There, the assumption appears to be that any referenced resources live in the same app. The paths built are always relative to the directory or the top of the static namespace, making it impossible to do the kind of references an extension author would want.

Well, almost impossible. I pretty much beat that into submission. And here it is: https://reviews.reviewboard.org/r/7437/

Read More