February | 2020 | Beanbag Blog

Hi everyone, and welcome to this week’s ChangeLog. This week, we want to talk about accessibility improvements for Review Board 4.0, and show you what this semester’s students are working on.

If you want to watch some videos instead of reading a bunch of stuff, jump down to Student Demo Videos!

Accessibility in Review Board

As we revise parts of our UI, introducing new features and designing new CSS Components, we have a goal of improving accessibility. We’re aiming to better support screen readers, improve keyboard navigation, and help people with visual impairments.

This will not be 100% implemented by 4.0, since we do plan to release sometime soon, but we will have laid the groundwork, working toward eventually being fully compliant with the Web Content Accessibility Guidelines (WCAG) 2.1.

There’s a lot that goes into accessibility on the web, but there’s two key areas that are important to get right, and are becoming a core part of our design and CSS component specifications: ARIA attributes and keyboard navigation.

ARIA attributes help screen readers and other assistive technologies understand, navigate, and communicate parts of the UI. They can communicate the intent of a UI component, provide more suitable labels or hints to screen readers, notify as important content updates, and more. They’re important, and we haven’t been good at using them, but they’re now being baked in to the design of any new UI we write.

Keyboard navigation is also very important. Not everyone can or wants to use a pointing device to navigate the UI, and we’ve identified several places where keyboard navigation (and focus presentation) is subpar or flat-out broken. So we’re making this a first-class citizen in new UIs, adding new keyboard shortcuts for important content areas or operations, and fixing cases where navigation is just busted.

To be clear, these aren’t the only focuses — there’s a lot more to the accessibility work than this. Improving accessibility is a long-term goal, and Review Board is a big product. We aren’t holding up 4.0 for this, but rather expect to spend time throughout the 4.0.x release cycle to gradually work on this.

And it’s a current focus of some of our student projects.

Student Demo Videos

In an earlier ChangeLog, we announced our new team of students working on Review Board. The big focuses this semester are on keyboard accessibility and first-time setup improvements.

They’ve been working hard for a month now, and have just completed their first (of three) demo videos. We’d like to show them off.

All videos are uploaded to our YouTube channel. Subscribe to keep up with content as we upload it.

Hannah Lin

Hannah’s been working on implementing keyboard navigation for file attachments, letting users focus on the attachments and control the pop-up menu (for reviewing, updating attachments, deleting, and downloading). That was her first warm-up project.

Her main project for the semester is working on a first-time setup guide, for new Review Board administrators. The goal is to help them get a new server up-and-running fast by walking them through the main setup steps as they progress through the administration UI.

Katherine Patenio

Katherine’s first demo covers some initial bug fixing work for RBTools on Python 3, addressing a problem where --help didn’t always work. She’s fixed this up and added a new layer of unit tests we can build upon.

Her main project for the semester isn’t covered here, but she’s going to be working on the rbt setup-repo command, helping streamline getting a new repository set up with Review Board.

Monica Bui

Monica’s also working on keyboard accessibility. Her focus in this demo is improving the New Review Request page, making sure that all elements can be tabbed to and navigated entirely by keyboard.

Xiaohui Liu

Xiaohui’s first project fixes up tab key navigation in the review request page. Previously, tabbing to fields would prioritize the fields on the right-hand side of review requests (Branch, Bugs, etc.) before the main fields (Description, Testing Done), which wasn’t really intuitive. His fix brings some sanity back to tab orders.

His second project is to implement common support in the UI for keyboard shortcuts, making it much easier for us to bake in better keyboard support on every page with less code to worry about.

Xiaole Zeng

Xiaole’s working on improving help within the product, giving users both a single place to go to when needing to find documentation or other useful information, and finding places within the UI where we can offer better inline guidance. For the latter, she’s working on adding helpful descriptions and documentation links when configuring repositories, based on the selected hosting service or repository type.

Next Week

We’re getting a new RBTools release ready to ship, so you’ll see that soon. We’re also testing 4.0 beta 1, and are getting that beta release on the calendar.

If you want to know more, have any questions, or are curious about anything else, please reach out on our community forum.

We’re also on Reddit (/r/reviewboard), Twitter, Facebook, and YouTube if you want other ways to keep up with Review Board and Beanbag.

Busy couple of weeks here. I’ve personally been sick, hence the lack of a ChangeLog last week. Sorry about that!

We’ve made a lot of great progress on getting Review Board 4.0 ready for beta, and updating the ecosystem of packages (such as Power Pack and Review Bot), but there is one urgent thing that came up that’s taking a bit of our time.

GitHub’s Authorization Changes

For many, many years, GitHub’s API has offered several options for authenticating with the API. Our initial integration with GitHub was written 10 years ago, and while it’s evolved over time, it’s continued to use the same original authentication methods to communicate with the API and link accounts.

In November, GitHub announced their were deprecating those methods. Frankly, due to its proximity to the holidays and some time-consuming work on our plate, this announcement slipped by us.

There are really two main ways in which this affects us:

HTTP requests to the API need to change how they pass API access tokens
We can no longer automatically exchange user credentials for an API access token when linking an account for a repository

GitHub API Authentication

GitHub’s APIs have historically taken an ?access_token=... parameter in API requests, and the original code we wrote to talk to the API continues to use this method. (If it ain’t broke…)

The modern approach is to make use of the HTTP Authorization header to pass in the access token. This is more standards-compliant and probably simplifies a lot of URL building and logging on their end.

This week, they began e-mailing users whose accounts were accessing the API using ?access_token=. You may have seen these, if you linked your GitHub account to Review Board. It’s annoying, but it’s designed to be, so that people update their software in time.

We’ve fixed this internally, and are testing to make sure it works everywhere. We’ll have a build out soon (see our timeline toward the bottom of this ChangeLog).

Linking GitHub Accounts

In order to talk to a source code repository, we typically need credentials of some kind. This may be a username and password, an API key/authentication token, or an SSH key.

Traditionally, we’ve been able to get by with taking the credentials right on the repository configuration page, combining the steps of linking an account and creating a repository. This is just easier for many reasons, and worked great with GitHub.

The GitHub process went like this:

We’d provide fields for a username and password to a GitHub account to use for repository access (though we’d never store the password).
When saving the repository, we’d use those credentials server-side to immediately make a request to GitHub’s Authorizations API to request a new access token.
We’d store that token and use it for all future API access.

This token was associated with the user’s account, and could be revoked at any point. We never had to store the password, like we unfortunately must do with some services that lack any form of authentication token capability.

This had always worked before, but it will be changing going forward, as the Authorizations APIs we used is now deprecated.

Short-term, we’ll be changing the dialog to provide instructions on how to generate a personal access token, and a field for providing it (instead of a password). This is an annoying extra step for users, but it’s a working solution we can employ short-term (and we already use this approach for some other services).

Long-term, we need to modernize the configuration experience, taking full advantage of OAuth web flows for linking accounts.

Challenges of OAuth in Review Board

First, let’s quickly go over OAuth (or, more specifically, OAuth2, the modern version of the standard).

OAuth is a standard way for a service (Service A) to request access to another service (Service B), on behalf of a user. You’ve probably seen basically this before when you’ve initiated a “Log In With Facebook” or when you’ve connected some service to Slack. You click a button, a browser window pops up and presents a page on Service B telling you that Service A wants access via your account, telling you what permissions it requests.

While complicated, it’s a pretty great thing to have in the modern world, but it’s not automatic.

Before Service A can even begin this process, someone must register it on Service B (through whatever mechanism is required by that service — this usually requires filling out a form). The result is a Client ID and a Client Secret, which must be stored somewhere and then used when initiating the OAuth process.

The Burden on Administrators

It’s very important that the Client ID and Secret are kept secure and not shared, and this is where things get more difficult for tools like Review Board.

Review Board is open source and self-installed, so we can’t supply a Client ID or Secret as part of the installation. That means an administrator must perform this task, and this can be a real annoyance when just getting started. It’s worse for some services than others.

Fortunately, it only has to be done once per required service, but we try to avoid this extra step when there are alternatives. We do take care of it on RBCommons so users don’t have to, at least.

In the case of GitHub, they’ve thought through this and have some mechanisms (such as App Manifests) we’re looking into that should aid in OAuth registration, but we haven’t yet figured out how this is going to work in the end.

Timeline: When Is This All Happening?

There’s no public information yet on when GitHub will be removing the old APIs, though we’ve been in communication with them and have a timeline we’re comfortable with. They’re still fairly early in the deprecation process, and have a history of handling deprecations very well.

We have three phases:

Update the API authentication method
Our plan is to release Review Board 3.0.17 early next week (targeting February 11th, 2020) with this fix.

We are not planning (at this time) to backport this to older generations of Review Board.
Request Personal Access Tokens when linking accounts

This is the manual version of what we’ve been doing behind the scenes. Users will need to generate their own token and supply it when linking an account.

We are planning to provide this a couple months before the API removal date. This is to keep the process nice and simple as long as possible, but to allow time for people to upgrade.
Implement an OAuth web-based account linking workflow

This will likely come sometime after the API removal, and will be in Review Board 4.0. We’ve been planning this anyway, and it’s not (at this time) needed to remain compatible with GitHub. Though it is the better method.

These plans may change as we go. We might decide to fast-track the OAuth web-based flow, for instance, based on other factors.

We still really want to get Review Board 4.0 wrapped up soon, and a lot of “urgent” things like this have come up, causing further delays, so we’re punting what we can for now.

Whew.

That was a lot to talk about.