Don't Miss Another Pull Request

Recently, I built a tiny script qpr to query GitHub pull requests via command line. The script itself is simple, but it increases our team's productivity quite a bit.

In this post, I am going to describe the problem we encountered and how we analyzed and solved it.

The Scenario

At Codementor, our dev team follows git flow, and we heavily use pull requests to do feature development and code review. With GitHub's webhooks and Slack integrations, we can be notified instantly when a pull request is created or assigned. However, most of the time when being notified, we are working on other features and not available to review the pull request immediately.

As a result, we often get messages like this on Slack:

Hey, can you please review this PR (link) when you're available?

Hiii, I've revised the PR based on your comments, can you please review it again?

Hey, did you merge the PR I approved yesterday? I didn't see it on develop branch.

Previous Solution

After receiving the above messages, we would visit the links to review or merge the pull requests. The primary pain point of this workflow is that we had to switch our context from the feature/bug we were working on to the pull requests. Needless to say, such context switches significantly lowered our productivity.

In addition to that, the release cycle became unpredictable when we forgot to merge those approved pull requests. To a team like Codementor which values release speed and user feedback, such situation gradually became intolerable as our team grew larger.

Define Our Problem

After some discussion within the team, we came up with the following questions:

1. Which of the pull requests were created by me and approved?
   (I should merge them ASAP.)

2. Which of the pull requests were created by me and required changes?
   (I should revise them and ask other team members to review them again.)

3. Which of the pull requests were waiting for me to review?
   (I should review them.)

After defining the problem, the next question we asked was "How and when do we need the answers to the questions?" A Slack bot might be fancy and fun at the first thought, but for people who live in the terminal (like us), a command line script might be better.

The Solution

After surveying GitHub Pull Request API document and finding nothing usable, we found GitHub's Issue Searching API that solved our problem.

Basically, it works by passing some searching quilifiers in the API calls.

Here are the three scenarios we discussed before:

Created by me and approved?

A single query qualifier can solve it:

author:<my-github-username> type:pr state:open review:approved

Created by me and requested changes?

The conditions are a little more complex.

Besides approved, we have two other kinds of review: Request Change and Comment. For our use case, we want to find pull requests that fall under two situations: requested changes and commented but not approved. Both of these cases mean we should revise our pull requests.

We use the following two search qualifiers to find these pull requests:

author:<my-github-username> type:pr state:open review:changes_requested
author:<my-github-username> type:pr state:open comments:>1 review:none

We use comments:>1 above because GitHub counts the initial description of the pull request as the first comment.

Waiting for me to review?

Two kinds of pull requests fall into this category:

1. Pull requests assigned to me that I haven't reviewed yet.
2. Pull requests which I requested changes on and are now revised.

The first kind of pull requests can be intuitively searched by:

type:pr state:open review-requested:<my-github-username>

But the second kind of pull requests are harder to search, as GitHub removes pull requests out of the review-requested category once it is reviewed.

Requested reviewers are no longer listed in the search results after they review a pull request.

This issue can be solved by asking the requester to re-assign the reviewer after revising his pull request. After the re-assignment, these pull requests can be searched by the qualifier above!

Hello qpr!

I wrapped the API calls above as a npm package: qpr (query-pull-request). It requires a user's GitHub access token with reading access to query private pull requests. Also, it provides a user filter to restrict repositories owned by a user or organization.

Any feedback or pull requests are highly appreciated!

Happy Pull Requesting! 💪