Julius Seporaitis
on hobbies and work



While at the core [The Tool] provides very similar code review facilities like Pull Requests on Github, Merge Requests on Gitlab, or Revisions on Phabricator, it is subtly different. The authors of [The Tool] assert that these subtle differences have a big impact on developer productivity and team output, and have seen this in action consistently.

At the early stage, today, these are the main differentiating factors:

Code Review Is Separate From Code Publishing

Github Pull Requests represent a branch with some feature code, and code reviews are closely linked with that branch. It works exceptionally well in open source projects, where large number of Pull Requests usually come in as features. However, in large, established, technology and/or startup projects, doing full-feature development all at once is risky. This has been slightly aleviated by Pull Request retargetting feature, but it comes with caveats and limitations, therefore not everyone can use it. From our experience, developers work around it through processes, like breaking down logical changes into commits, that make it work, but at the cost of velocity being dragged down. Developers are constantly at odds of either doing a big risky change or building a sequence of small Pull Requests, but in a waterfall fashion.

Phabricator Revisions, on the other hand, separate the code publishing from code review. This article explains it in depth. This difference is a subtle and hard to evaluate, but the authors of [The Tool] have anecdotal experience, of using Phabricator. Teams that were using Phabricator were between 20-50% more productive, in terms of material output in production. On the other hand, setting up Phabricator, and migrating to Differential Revisions, is complicated. It requires a separate command line tool called Arcanist, or arc in short. It is also completely incompatible with GitHub Pull Requests, in a way that both cannot be used at the same time. Finally, Phabricator has been discontinued since 2021.

[The Tool] tries to pick up where Phabricator treaded the path. Just like Phabricator, it separates the code review from the change itself. However, distinctly, it lowers the entry bar and cost of trying [The Tool]. There are no custom command line tools, and developers can easily switch between using [The Tool] and Github or even Phabricator.

Workflow Driven / Signal vs Noise

Code reviews on Github are based on an inbox model. Again, this works really well on open-source projects, but in large scale tech projects this model causes a lot of noise, as every interaction with a Pull Request is a notification. Authors of [The Tool] have been left frustrated in multiple large scale tech companies either by overwhelmed email inbox or notification list on Github UI.

This low signal to noise ratio most often results in developers looking for workarounds. One of them is pinging other developers via a real-time communications platform (e.g. Slack), asking to do the code review. Not to diminish from a societal problem, but this is something that is called review begging. There are multiple problems with it. First, the expectation of when the review will happen is not clear, because the message might have drowned among other chat messages. Second, acknowledging or reviewing it immediately breaks the flow of the reviewer. Third, the reviewer may not even be explicitly defined on the Pull Request, making it unclear for other team members if they can or cannot step in.

Phabricator solved this problem by focussing on the developer workflow, which authors of [The Tool] consider more appropriate in large private tech teams. A developer can open the Differential code review dashboard and see all the important information. The below list seems long, but it solves all the issues inbox model had - no noise and no pinging. The developer opens up a page and can instantly see what they need to work on next.

  • Must Review - changes that have went through one review cycle.
  • Ready to Review - freshly submitted changes for review.
  • Ready to Land - user’s changes that are approved and ready to be merged into main branch.
  • Ready to Update - user’s changes after reviewer feedback.
  • Drafts - user’s work in progress changes
  • Waiting on Review - user’s changes waiting on reviews.
  • Waiting on Authors - changes that user has reviewed, but that are waiting on author’s updates.
  • Waiting on Other Reviewers - changes that have been reviewed by the user, but waiting for other reviewers.

[The Tool] draws inspiration from this model and will provide workflow driven dashboard, that will make it easy to distinguish between the different changes.

Low Entry Bar

Github democratised version control and made it accessible to everyone. Github Pull Requests are really easy to start and use. However, as mentioned in other points, there are some drawbacks to this model.

Phabricator provided an alternative to Pull Requests, however the cost of trying, switching and using it is far greater than Github. It is impossible to say “let’s try Phabricator on repository X for a week and see what happens.”

[The Tool], in contrast, strives to make it just as easy to have an alternatie to Github Pull Requests, as Github’s own Pull Requests.

Good Practices Driven

Github Pull Request default change application model is through merge commits. While there is nothing inherently bad about them, merge commits lead to a largely messy Git history tree. One argument for that is, this preserves the history of the change in the Git history. The authors of [The Tool] found that the intermediary commits in virtually all projects they worked on to be irrelevant. Another change application model is to squash the PR into one commit and apply it onto main branch. Unfortunately, Github interface for shortlog and description input is a plain old HTML textarea field, which is wholly inadequate. While there are ways to set PR templates, these are often left in the PR description, and not committed to Git history. Even if developers try to write good commit / PR messages, the end result in most cases is still a messy Git history, that contains zero useful information. In other words, for the purposes of understanding changes, the repository alone is useless without access to Github.

Phabricator, in contrast, squashed all commits in a change and enforced a consistent format on the final commit applied on main branch. Looking at the Git log, you could tell not only the title, summary and how the change was tested, but more importantly - who were the reviewers, who actually approved the change, link to task, as well as link to the Revision on Phabricator, in case there is a need to read the code review discussions. Plus, there was an option to add additional structured information, if needed.

[The Tool], in this early stage, does not enforce a strict format, like Phabricator did, but because it relies on standard Git tooling and concepts, it is much easier to have a clean and useful Git history, by writing the first commit message well, when running git commit.